Skip to content

Commit de2d0d3

Browse files
kattnikattni
authored
Merge pull request #16 from sommersoft/new_docs
Improve Ref Docs
2 parents eb7720b + 81e08ce commit de2d0d3

File tree

12 files changed

+291
-26
lines changed

12 files changed

+291
-26
lines changed

‎readthedocs.yml renamed to ‎.readthedocs.yml

-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
11
python:
22
version: 3
3-
pip_install: true
43
requirements_file: requirements.txt

‎.travis.yml

+4-2
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,17 @@ deploy:
1616
provider: releases
1717
api_key: $GITHUB_TOKEN
1818
file_glob: true
19-
file: bundles/*
19+
file: $TRAVIS_BUILD_DIR/bundles/*
2020
skip_cleanup: true
21+
overwrite: true
2122
on:
2223
tags: true
2324

2425
install:
25-
- pip install pylint circuitpython-build-tools
26+
- pip install pylint circuitpython-build-tools Sphinx sphinx-rtd-theme
2627

2728
script:
2829
- pylint adafruit_bus_device/*.py
2930
- ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
3031
- circuitpython-build-bundles --filename_prefix adafruit-circuitpython-bus-device --library_location .
32+
- cd docs && sphinx-build -E -W -b html . _build/html

‎README.rst

+64-7
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,14 @@ Adafruit CircuitPython BusDevice
66
:alt: Documentation Status
77

88
.. image :: https://img.shields.io/discord/327254708534116352.svg
9-
:target: https://adafru.it/discord
9+
:target: https://discord.gg/nBQh6qu
1010
:alt: Discord
1111
12-
The `I2CDevice` and `SPIDevice` helper classes make managing transaction state
12+
.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_BusDevice.svg?branch=master
13+
:target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_BusDevice
14+
:alt: Build Status
15+
16+
The ``I2CDevice`` and ``SPIDevice`` helper classes make managing transaction state
1317
on a bus easy. For example, they manage locking the bus to prevent other
1418
concurrent access. For SPI devices, it manages the chip select and protocol
1519
changes such as mode. For I2C, it manages the device address.
@@ -28,9 +32,62 @@ To install:
2832
#. Download and unzip the `latest release zip <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice/releases>`_.
2933
#. Copy the unzipped ``adafruit_bus_device`` to the ``lib`` directory on the ``CIRCUITPY`` drive.
3034

31-
API
32-
---
33-
.. toctree::
34-
:maxdepth: 3
35+
Usage Example
36+
=============
37+
38+
See examples/read_register_i2c.py and examples/read_register_spi.py for examples of the module's usage.
39+
40+
Contributing
41+
============
42+
43+
Contributions are welcome! Please read our `Code of Conduct
44+
<https://github.com/adafruit/Adafruit_CircuitPython_BusDevice/blob/master/CODE_OF_CONDUCT.md>`_
45+
before contributing to help this project stay welcoming.
46+
47+
Building locally
48+
================
49+
50+
To build this library locally you'll need to install the
51+
`circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
52+
53+
.. code-block:: shell
54+
55+
python3 -m venv .env
56+
source .env/bin/activate
57+
pip install circuitpython-build-tools
58+
59+
Once installed, make sure you are in the virtual environment:
60+
61+
.. code-block:: shell
62+
63+
source .env/bin/activate
64+
65+
Then run the build:
66+
67+
.. code-block:: shell
68+
69+
circuitpython-build-bundles --filename_prefix adafruit-circuitpython-busdevice --library_location .
70+
71+
Sphinx documentation
72+
-----------------------
73+
74+
Sphinx is used to build the documentation based on rST files and comments in the code. First,
75+
install dependencies (feel free to reuse the virtual environment from above):
76+
77+
.. code-block:: shell
78+
79+
python3 -m venv .env
80+
source .env/bin/activate
81+
pip install Sphinx sphinx-rtd-theme
82+
83+
Now, once you have the virtual environment activated:
84+
85+
.. code-block:: shell
86+
87+
cd docs
88+
sphinx-build -E -W -b html . _build/html
89+
90+
This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
91+
view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
92+
locally verify it will pass.
3593

36-
adafruit_bus_device/index

‎adafruit_bus_device/i2c_device.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
# THE SOFTWARE.
2222

2323
"""
24-
I2C Bus Device
24+
`adafruit_bus_device.i2c_device` - I2C Bus Device
2525
====================================================
2626
"""
2727

‎adafruit_bus_device/index.rst

-14
This file was deleted.

‎adafruit_bus_device/spi_device.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
# pylint: disable=too-few-public-methods
2323

2424
"""
25-
SPI Bus Device
25+
`adafruit_bus_device.spi_device` - SPI Bus Device
2626
====================================================
2727
"""
2828

‎docs/_static/favicon.ico

4.31 KB
Binary file not shown.

‎docs/api.rst

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
2+
.. If you created a package, create one automodule per module in the package.
3+
4+
.. automodule:: adafruit_bus_device.i2c_device
5+
:members:
6+
7+
.. automodule:: adafruit_bus_device.spi_device
8+
:members:

‎docs/conf.py

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# -*- coding: utf-8 -*-
2+
3+
import os
4+
import sys
5+
sys.path.insert(0, os.path.abspath('..'))
6+
7+
# -- General configuration ------------------------------------------------
8+
9+
# Add any Sphinx extension module names here, as strings. They can be
10+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
11+
# ones.
12+
extensions = [
13+
'sphinx.ext.autodoc',
14+
'sphinx.ext.intersphinx',
15+
'sphinx.ext.viewcode',
16+
]
17+
18+
# Uncomment the below if you use native CircuitPython modules such as
19+
# digitalio, micropython and busio. List the modules you use. Without it, the
20+
# autodoc module docs will fail to generate with a warning.
21+
#autodoc_mock_imports = ["adafruit_bus_device", "micropython"]
22+
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)}
24+
25+
# Add any paths that contain templates here, relative to this directory.
26+
templates_path = ['_templates']
27+
28+
source_suffix = '.rst'
29+
30+
# The master toctree document.
31+
master_doc = 'index'
32+
33+
# General information about the project.
34+
project = u'Adafruit CircuitPython Bus Device'
35+
copyright = u'2016-2017 Scott Shawcroft and Tony Dicola for Adafruit Industries'
36+
author = u'Scott Shawcroft and Tony Dicola'
37+
38+
# The version info for the project you're documenting, acts as replacement for
39+
# |version| and |release|, also used in various other places throughout the
40+
# built documents.
41+
#
42+
# The short X.Y version.
43+
version = u'1.0'
44+
# The full version, including alpha/beta/rc tags.
45+
release = u'1.0'
46+
47+
# The language for content autogenerated by Sphinx. Refer to documentation
48+
# for a list of supported languages.
49+
#
50+
# This is also used if you do content translation via gettext catalogs.
51+
# Usually you set "language" from the command line for these cases.
52+
language = None
53+
54+
# List of patterns, relative to source directory, that match files and
55+
# directories to ignore when looking for source files.
56+
# This patterns also effect to html_static_path and html_extra_path
57+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
58+
59+
# The reST default role (used for this markup: `text`) to use for all
60+
# documents.
61+
#
62+
default_role = "any"
63+
64+
# If true, '()' will be appended to :func: etc. cross-reference text.
65+
#
66+
add_function_parentheses = True
67+
68+
# The name of the Pygments (syntax highlighting) style to use.
69+
pygments_style = 'sphinx'
70+
71+
# If true, `todo` and `todoList` produce output, else they produce nothing.
72+
todo_include_todos = False
73+
74+
# If this is True, todo emits a warning for each TODO entries. The default is False.
75+
todo_emit_warnings = True
76+
77+
78+
# -- Options for HTML output ----------------------------------------------
79+
80+
# The theme to use for HTML and HTML Help pages. See the documentation for
81+
# a list of builtin themes.
82+
#
83+
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
84+
85+
if not on_rtd: # only import and set the theme if we're building docs locally
86+
try:
87+
import sphinx_rtd_theme
88+
html_theme = 'sphinx_rtd_theme'
89+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']
90+
except:
91+
html_theme = 'default'
92+
html_theme_path = ['.']
93+
else:
94+
html_theme_path = ['.']
95+
96+
# Add any paths that contain custom static files (such as style sheets) here,
97+
# relative to this directory. They are copied after the builtin static files,
98+
# so a file named "default.css" will overwrite the builtin "default.css".
99+
html_static_path = ['_static']
100+
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+
107+
# Output file base name for HTML help builder.
108+
htmlhelp_basename = 'AdafruitBusDeviceLibrarydoc'
109+
110+
# -- Options for LaTeX output ---------------------------------------------
111+
112+
latex_elements = {
113+
# The paper size ('letterpaper' or 'a4paper').
114+
#
115+
# 'papersize': 'letterpaper',
116+
117+
# The font size ('10pt', '11pt' or '12pt').
118+
#
119+
# 'pointsize': '10pt',
120+
121+
# Additional stuff for the LaTeX preamble.
122+
#
123+
# 'preamble': '',
124+
125+
# Latex figure (float) alignment
126+
#
127+
# 'figure_align': 'htbp',
128+
}
129+
130+
# Grouping the document tree into LaTeX files. List of tuples
131+
# (source start file, target name, title,
132+
# author, documentclass [howto, manual, or own class]).
133+
latex_documents = [
134+
(master_doc, 'AdafruitBusDeviceLibrary.tex', u'Adafruit Bus Device Library Documentation',
135+
author, 'manual'),
136+
]
137+
138+
# -- Options for manual page output ---------------------------------------
139+
140+
# One entry per manual page. List of tuples
141+
# (source start file, name, description, authors, manual section).
142+
man_pages = [
143+
(master_doc, 'AdafruitBusDeviceLibrary', u'Adafruit Bus Device Library Documentation',
144+
[author], 1)
145+
]
146+
147+
# -- Options for Texinfo output -------------------------------------------
148+
149+
# Grouping the document tree into Texinfo files. List of tuples
150+
# (source start file, target name, title, author,
151+
# dir menu entry, description, category)
152+
texinfo_documents = [
153+
(master_doc, 'AdafruitBusDeviceLibrary', u'Adafruit Bus Device Library Documentation',
154+
author, 'AdafruitBusDeviceLibrary', 'One line description of project.',
155+
'Miscellaneous'),
156+
]

‎conf.py renamed to ‎docs/conf_old.py

File renamed without changes.

‎docs/examples.rst

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Simple test
2+
------------
3+
4+
Ensure your device works with this simple test.
5+
6+
.. literalinclude:: ../examples/read_register_i2c.py
7+
:caption: examples/read_register_i2c.py
8+
:linenos:
9+
10+
.. literalinclude:: ../examples/read_register_spi.py
11+
:caption: examples/read_register_spi.py
12+
:linenos:

‎docs/index.rst

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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+
.. toctree::
30+
:caption: Other Links
31+
32+
Download <https://github.com/adafruit/Adafruit_CircuitPython_BusDevice/releases/latest>
33+
CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
34+
CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
35+
Discord Chat <https://adafru.it/discord>
36+
Adafruit Learning System <https://learn.adafruit.com>
37+
Adafruit Blog <https://blog.adafruit.com>
38+
Adafruit Store <https://www.adafruit.com>
39+
40+
Indices and tables
41+
==================
42+
43+
* :ref:`genindex`
44+
* :ref:`modindex`
45+
* :ref:`search`

0 commit comments

Comments
 (0)