Skip to content
This repository was archived by the owner on Oct 29, 2019. It is now read-only.

Commit 8a8900d

Browse files
authored
Merge pull request #4 from sommersoft/new_docs
Improve Ref Docs
2 parents c4ced65 + 21dfdf8 commit 8a8900d

File tree

9 files changed

+130
-15
lines changed

9 files changed

+130
-15
lines changed
File renamed without changes.

.travis.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,17 @@ deploy:
1616
provider: releases
1717
api_key: $GH_REPO_TOKEN
1818
file_glob: true
19-
file: bundles/*
19+
file: $TRAVIS_BUILD_DIR/bundles/*
2020
skip_cleanup: true
2121
overwrite: true
2222
on:
2323
tags: true
2424

2525
install:
26-
- pip install pylint circuitpython-build-tools
26+
- pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
2727

2828
script:
2929
- pylint adafruit_lsm303.py
3030
- ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name,bad-whitespace examples/*/*.py)
3131
- circuitpython-build-bundles --filename_prefix adafruit-circuitpython-lsm303 --library_location .
32+
- cd docs && sphinx-build -E -W -b html . _build/html

README.rst

Lines changed: 28 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ Introduction
1010
:target: https://discord.gg/nBQh6qu
1111
:alt: Discord
1212
13+
.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_LSM303.svg?branch=master
14+
:target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_LSM303
15+
:alt: Build Status
16+
1317
Adafruit CircuitPython module for the LSM303 6-DoF with 3-axis accelerometer and magnetometer
1418

1519
Dependencies
@@ -49,14 +53,6 @@ Usage Example
4953
time.sleep(1.0)
5054
5155
52-
API Reference
53-
=============
54-
55-
.. toctree::
56-
:maxdepth: 2
57-
58-
api
59-
6056
Contributing
6157
============
6258

@@ -87,3 +83,27 @@ Then run the build:
8783
.. code-block:: shell
8884
8985
circuitpython-build-bundles --filename_prefix adafruit-circuitpython-lsm303 --library_location .
86+
87+
88+
Sphinx documentation
89+
-----------------------
90+
91+
Sphinx is used to build the documentation based on rST files and comments in the code. First,
92+
install dependencies (feel free to reuse the virtual environment from above):
93+
94+
.. code-block:: shell
95+
96+
python3 -m venv .env
97+
source .env/bin/activate
98+
pip install Sphinx sphinx-rtd-theme
99+
100+
Now, once you have the virtual environment activated:
101+
102+
.. code-block:: shell
103+
104+
cd docs
105+
sphinx-build -E -W -b html . _build/html
106+
107+
This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
108+
view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
109+
locally verify it will pass.

adafruit_lsm303.py

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,30 @@
2020
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
2121
# THE SOFTWARE.
2222
"""
23-
`adafruit_LSM303`
23+
`adafruit_lsm303`
2424
====================================================
2525
2626
2727
CircuitPython driver for the LSM303 accelerometer + magnetometer.
2828
2929
* Author(s): Dave Astels
30+
31+
Implementation Notes
32+
--------------------
33+
34+
**Hardware:**
35+
36+
* Adafruit `Triple-axis Accelerometer+Magnetometer (Compass) Board - LSM303
37+
<https://www.adafruit.com/product/1120>`_ (Product ID: 1120)
38+
* Adafruit `FLORA Accelerometer/Compass Sensor - LSM303 - v1.0
39+
<https://www.adafruit.com/product/1247>`_ (Product ID: 1247)
40+
41+
**Software and Dependencies:**
42+
43+
* Adafruit CircuitPython firmware for the ESP8622 and M0-based boards:
44+
https://github.com/adafruit/circuitpython/releases
45+
* Adafruit's Bus Device library:
46+
https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
3047
"""
3148

3249
try:

docs/_static/favicon.ico

4.31 KB
Binary file not shown.

api.rst renamed to docs/api.rst

File renamed without changes.

conf.py renamed to docs/conf.py

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
import os
44
import sys
5-
sys.path.insert(0, os.path.abspath('.'))
5+
sys.path.insert(0, os.path.abspath('..'))
66

77
# -- General configuration ------------------------------------------------
88

@@ -20,15 +20,15 @@
2020
# autodoc module docs will fail to generate with a warning.
2121
autodoc_mock_imports = ["micropython", "adafruit_bus_device"]
2222

23-
intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'BusDevice': ('https://circuitpython.readthedocs.io/projects/bus_device/en/latest/', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
23+
intersphinx_mapping = {'python': ('https://docs.python.org/3.4', None),'BusDevice': ('https://circuitpython.readthedocs.io/projects/busdevice/en/latest/', None),'CircuitPython': ('https://circuitpython.readthedocs.io/en/latest/', None)}
2424

2525
# Add any paths that contain templates here, relative to this directory.
2626
templates_path = ['_templates']
2727

2828
source_suffix = '.rst'
2929

3030
# The master toctree document.
31-
master_doc = 'README'
31+
master_doc = 'index'
3232

3333
# General information about the project.
3434
project = u'Adafruit LSM303 Library'
@@ -54,7 +54,7 @@
5454
# List of patterns, relative to source directory, that match files and
5555
# directories to ignore when looking for source files.
5656
# This patterns also effect to html_static_path and html_extra_path
57-
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
57+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
5858

5959
# The reST default role (used for this markup: `text`) to use for all
6060
# documents.
@@ -71,6 +71,9 @@
7171
# If true, `todo` and `todoList` produce output, else they produce nothing.
7272
todo_include_todos = False
7373

74+
# If this is True, todo emits a warning for each TODO entries. The default is False.
75+
todo_emit_warnings = True
76+
7477

7578
# -- Options for HTML output ----------------------------------------------
7679

@@ -95,6 +98,12 @@
9598
# so a file named "default.css" will overwrite the builtin "default.css".
9699
html_static_path = ['_static']
97100

101+
# The name of an image file (relative to this directory) to use as a favicon of
102+
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
103+
# pixels large.
104+
#
105+
html_favicon = '_static/favicon.ico'
106+
98107
# Output file base name for HTML help builder.
99108
htmlhelp_basename = 'AdafruitLsm303Librarydoc'
100109

docs/examples.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Simple tests
2+
------------
3+
4+
Ensure your device works with these simple tests.
5+
6+
.. literalinclude:: ../examples/fast_accel/fast_accel.py
7+
:caption: examples/fast_accel/fast_accel.py
8+
:linenos:
9+
10+
.. literalinclude:: ../examples/fast_mag/fast_mag.py
11+
:caption: examples/fast_mag/fast_mag.py
12+
:linenos:
13+
14+
.. literalinclude:: ../examples/slow_both/slow_both.py
15+
:caption: examples/slow_both/slow_both.py
16+
:linenos:
17+
18+
.. literalinclude:: ../examples/raw_and_cooked/raw_and_cooked.py
19+
:caption: examples/raw_and_cooked/raw_and_cooked.py
20+
:linenos:

docs/index.rst

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
.. include:: ../README.rst
2+
3+
Table of Contents
4+
=================
5+
6+
.. toctree::
7+
:maxdepth: 4
8+
:hidden:
9+
10+
self
11+
12+
.. toctree::
13+
:caption: Examples
14+
15+
examples
16+
17+
.. toctree::
18+
:caption: API Reference
19+
:maxdepth: 3
20+
21+
api
22+
23+
.. toctree::
24+
:caption: Tutorials
25+
26+
.. toctree::
27+
:caption: Related Products
28+
29+
Triple-axis Accelerometer+Magnetometer (Compass) Board - LSM303 <https://www.adafruit.com/product/1120>
30+
FLORA Accelerometer/Compass Sensor - LSM303 - v1.0 <https://www.adafruit.com/product/1247>
31+
32+
.. toctree::
33+
:caption: Other Links
34+
35+
Download <https://github.com/adafruit/Adafruit_CircuitPython_LSM303/releases/latest>
36+
CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
37+
CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
38+
Discord Chat <https://adafru.it/discord>
39+
Adafruit Learning System <https://learn.adafruit.com>
40+
Adafruit Blog <https://blog.adafruit.com>
41+
Adafruit Store <https://www.adafruit.com>
42+
43+
Indices and tables
44+
==================
45+
46+
* :ref:`genindex`
47+
* :ref:`modindex`
48+
* :ref:`search`

0 commit comments

Comments
 (0)