Skip to content

Commit 1b12b6e

Browse files
authored
Merge pull request adafruit#4 from sommersoft/new_docs
Improve Ref Docs
2 parents 81f3591 + 958a40a commit 1b12b6e

File tree

9 files changed

+120
-13
lines changed

9 files changed

+120
-13
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: $GITHUB_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_rtttl.py
3030
- ([[ ! -d "examples" ]] || pylint --disable=missing-docstring,invalid-name examples/*.py)
3131
- circuitpython-build-bundles --filename_prefix adafruit-circuitpython-rtttl --library_location .
32+
- cd docs && sphinx-build -E -W -b html . _build/html

README.rst

Lines changed: 52 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@ Introduction
66
:target: https://circuitpython.readthedocs.io/projects/rtttl/en/latest/
77
:alt: Documentation Status
88

9-
.. image :: https://badges.gitter.im/adafruit/circuitpython.svg
10-
:target: https://gitter.im/adafruit/circuitpython?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
11-
:alt: Gitter
9+
.. image :: https://img.shields.io/discord/327254708534116352.svg
10+
:target: https://discord.gg/nBQh6qu
11+
:alt: Discord
12+
13+
.. image:: https://travis-ci.org/adafruit/Adafruit_CircuitPython_RTTTL.svg?branch=master
14+
:target: https://travis-ci.org/adafruit/Adafruit_CircuitPython_RTTTL
15+
:alt: Build Status
1216

1317
This plays `RTTTL <https://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language>`_ melodies.
1418

@@ -42,10 +46,50 @@ Contributions are welcome! Please read our `Code of Conduct
4246
<https://github.com/adafruit/Adafruit_CircuitPython_rtttl/blob/master/CODE_OF_CONDUCT.md>`_
4347
before contributing to help this project stay welcoming.
4448

45-
API Reference
46-
=============
49+
Building locally
50+
================
51+
52+
To build this library locally you'll need to install the
53+
`circuitpython-build-tools <https://github.com/adafruit/circuitpython-build-tools>`_ package.
54+
55+
.. code-block:: shell
56+
57+
python3 -m venv .env
58+
source .env/bin/activate
59+
pip install circuitpython-build-tools
60+
61+
Once installed, make sure you are in the virtual environment:
62+
63+
.. code-block:: shell
64+
65+
source .env/bin/activate
66+
67+
Then run the build:
68+
69+
.. code-block:: shell
70+
71+
circuitpython-build-bundles --filename_prefix adafruit-circuitpython-rtttl --library_location .
72+
73+
Sphinx documentation
74+
-----------------------
75+
76+
Sphinx is used to build the documentation based on rST files and comments in the code. First,
77+
install dependencies (feel free to reuse the virtual environment from above):
78+
79+
.. code-block:: shell
80+
81+
python3 -m venv .env
82+
source .env/bin/activate
83+
pip install Sphinx sphinx-rtd-theme
84+
85+
Now, once you have the virtual environment activated:
86+
87+
.. code-block:: shell
88+
89+
cd docs
90+
sphinx-build -E -W -b html . _build/html
4791
48-
.. toctree::
49-
:maxdepth: 2
92+
This will output the documentation to ``docs/_build/html``. Open the index.html in your browser to
93+
view them. It will also (due to -W) error out on any warning like Travis will. This is a good way to
94+
locally verify it will pass.
5095

51-
api

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: 12 additions & 3 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

@@ -25,7 +25,7 @@
2525
source_suffix = '.rst'
2626

2727
# The master toctree document.
28-
master_doc = 'README'
28+
master_doc = 'index'
2929

3030
# General information about the project.
3131
project = u'Adafruit RTTTL Library'
@@ -51,7 +51,7 @@
5151
# List of patterns, relative to source directory, that match files and
5252
# directories to ignore when looking for source files.
5353
# This patterns also effect to html_static_path and html_extra_path
54-
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
54+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.env', 'CODE_OF_CONDUCT.md']
5555

5656
# The reST default role (used for this markup: `text`) to use for all
5757
# documents.
@@ -68,6 +68,9 @@
6868
# If true, `todo` and `todoList` produce output, else they produce nothing.
6969
todo_include_todos = False
7070

71+
# If this is True, todo emits a warning for each TODO entries. The default is False.
72+
todo_emit_warnings = True
73+
7174

7275
# -- Options for HTML output ----------------------------------------------
7376

@@ -92,6 +95,12 @@
9295
# so a file named "default.css" will overwrite the builtin "default.css".
9396
html_static_path = ['_static']
9497

98+
# The name of an image file (relative to this directory) to use as a favicon of
99+
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
100+
# pixels large.
101+
#
102+
html_favicon = '_static/favicon.ico'
103+
95104
# Output file base name for HTML help builder.
96105
htmlhelp_basename = 'AdafruitRTTTLLibrarydoc'
97106

docs/examples.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Simple test
2+
-------------
3+
4+
Ensure your device works with this simple test.
5+
6+
.. literalinclude:: ../examples/rtttl_simpletest.py
7+
:caption: examples/rtttl_simpletest.py
8+
:linenos:

docs/index.rst

Lines changed: 45 additions & 0 deletions
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_RTTTL/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`
File renamed without changes.

0 commit comments

Comments
 (0)