8000 Documentation rework to unify the docs together rather than having them · cpforbes/circuitpython@46e7f8e · GitHub
[go: up one dir, main page]
Skip to content

Commit 46e7f8e

Browse files
tannewttannewt
committed
Documentation rework to unify the docs together rather than having them
on a per port basis. Also enables generating docs from inline RST in C code. Simply omits all lines except those that start with //|. Indentation after "//| " will be preserved.
1 parent cb99ae5 commit 46e7f8e

26 files changed

+183
-746
lines changed

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,7 @@ __pycache__/
3939
######################
4040
GNUmakefile
4141
user.props
42+
43+
# Sphinx output
44+
###############
45+
_build

‎c2rst.py

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import sphinx.parsers
2+
import docutils.parsers.rst as rst
3+
4+
class CStrip(sphinx.parsers.Parser):
5+
def __init__(self):
6+
self.rst_parser = rst.Parser()
7+
8+
def parse(self, inputstring, document):
9+
stripped = []
10+
for line in inputstring.split("\n"):
11+
line = line.strip()
12+
if line == "//|":
13+
stripped.append("")
14+
elif line.startswith("//| "):
15+
stripped.append(line[len("//| "):])
16+
stripped = "\r\n".join(stripped)
17+
self.rst_parser.parse(stripped, document)

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

Lines changed: 11 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -21,46 +21,14 @@
2121
# documentation root, use os.path.abspath to make it absolute, like shown here.
2222
sys.path.insert(0, os.path.abspath('.'))
2323

24-
# Work out the port to generate the docs for
25-
from collections import OrderedDict
26-
micropy_port = os.getenv('MICROPY_PORT') or 'pyboard'
27-
tags.add('port_' + micropy_port)
28-
ports = OrderedDict((
29-
('unix', 'unix'),
30-
('pyboard', 'the pyboard'),
31-
('wipy', 'the WiPy'),
32-
('esp8266', 'the ESP8266'),
33-
))
34-
35-
# The members of the html_context dict are available inside topindex.html
36-
micropy_version = os.getenv('MICROPY_VERSION') or 'latest'
37-
micropy_all_versions = (os.getenv('MICROPY_ALL_VERSIONS') or 'latest').split(',')
38-
url_pattern = '%s/en/%%s/%%s' % (os.getenv('MICROPY_URL_PREFIX') or '/',)
39-
html_context = {
40-
'port':micropy_port,
41-
'port_name':ports[micropy_port],
42-
'port_version':micropy_version,
43-
'all_ports':[
44-
(port_id, url_pattern % (micropy_version, port_id))
45-
for port_id, port_name in ports.items()
46-
],
47-
'all_versions':[
48-
(ver, url_pattern % (ver, micropy_port))
49-
for ver in micropy_all_versions
50-
],
51-
'downloads':[
52-
('PDF', url_pattern % (micropy_version, 'micropython-%s.pdf' % micropy_port)),
53-
],
54-
}
55-
5624

5725
# Specify a custom master document based on the port name
58-
master_doc = micropy_port + '_' + 'index'
26+
master_doc = 'index'
5927

6028
# -- General configuration ------------------------------------------------
6129

6230
# If your documentation needs a minimal Sphinx version, state it here.
63-
#needs_sphinx = '1.0'
31+
needs_sphinx = '1.3'
6432

6533
# Add any Sphinx extension module names here, as strings. They can be
6634
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
@@ -70,17 +38,16 @@
7038
'sphinx.ext.doctest',
7139
'sphinx.ext.intersphinx',
7240
'sphinx.ext.todo',
73-
'sphinx.ext.coverage',
74-
'sphinx_selective_exclude.modindex_exclude',
75-
'sphinx_selective_exclude.eager_only',
76-
'sphinx_selective_exclude.search_auto_exclude',
41+
'sphinx.ext.coverage'
7742
]
7843

7944
# Add any paths that contain templates here, relative to this directory.
8045
templates_path = ['templates']
8146

8247
# The suffix of source filenames.
83-
source_suffix = '.rst'
48+
source_suffix = ['.rst', '.md', '.c', '.h']
49+
50+
source_parsers = {'.c': "c2rst.CStrip", '.h': "c2rst.CStrip"}
8451

8552
# The encoding of source files.
8653
#source_encoding = 'utf-8-sig'
@@ -89,8 +56,8 @@
8956
#master_doc = 'index'
9057

9158
# General information about the project.
92-
project = 'MicroPython'
93-
copyright = '2014-2016, Damien P. George and contributors'
59+
project = 'Adafruit\'s MicroPython'
60+
copyright = '2014-2016, Damien P. George, Scott Shawcroft, Tony DiCola and other contributors'
9461

9562
# The version info for the project you're documenting, acts as replacement for
9663
# |version| and |release|, also used in various other places throughout the
@@ -113,7 +80,7 @@
11380

11481
# List of patterns, relative to source directory, that match files and
11582
# directories to ignore when looking for source files.
116-
exclude_patterns = ['build']
83+
exclude_patterns = ["*/build-*", "atmel-samd/asf", "atmel-samd/**.c", "atmel-samd/**.h", "bare-arm", "cc3200", "cc3200/FreeRTOS", "cc3200/hal", "drivers", "esp8266", "examples", "extmod", "lib", "minimal", "mpy-cross", "pic16bit", "py", "qemu-arm", "stmhal", "stmhal/hal", "stmhal/cmsis", "stmhal/usbdev", "stmhal/usbhost", "teensy", "tests", "tools", "unix", "windows", "zephyr"]
11784

11885
# The reST default role (used for this markup: `text`) to use for all
11986
# documents.
@@ -183,7 +150,7 @@
183150
# Add any paths that contain custom static files (such as style sheets) here,
184151
# relative to this directory. They are copied after the builtin static files,
185152
# so a file named "default.css" will overwrite the builtin "default.css".
186-
html_static_path = ['static']
153+
html_static_path = ['docs/static']
187154

188155
# Add any extra paths that contain custom files (such as robots.txt or
189156
# .htaccess) here, relative to this directory. These files are copied
@@ -203,7 +170,7 @@
203170

204171
# Additional templates that should be rendered to pages, maps page names to
205172
# template names.
206-
html_additional_pages = {"index": "topindex.html"}
173+
#html_additional_pages = {"index": "topindex.html"}
207174

208175
# If false, no module index is generated.
209176
#html_domain_indices = True
@@ -316,24 +283,3 @@
316283

317284
# Example configuration for intersphinx: refer to the Python standard library.
318285
intersphinx_mapping = {'http://docs.python.org/': None}
319-
320-
# Append the other ports' specific folders/files to the exclude pattern
321-
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
322-
323-
modules_port_specific = {
324-
'pyboard': ['pyb'],
325-
'wipy': ['wipy'],
326-
'esp8266': ['esp'],
327-
}
328-
329-
modindex_exclude = []
330-
331-
for p, l in modules_port_specific.items():
332-
if p != micropy_port:
333-
modindex_exclude += l
334-
335-
# Exclude extra modules per port
336-
modindex_exclude += {
337-
'esp8266': ['cmath', 'select'],
338-
'wipy': ['cmath'],
339-
}.get(micropy_port, [])

‎docs/Makefile

Lines changed: 0 additions & 180 deletions
This file was deleted.

‎docs/README.md

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
1-
MicroPython Documentation
1+
Adafruit's MicroPython Documentation
22
=========================
33

4-
The MicroPython documentation can be found at:
5-
http://docs.micropython.org/en/latest/
4+
The latest documentation can be found at:
5+
http://adafruit-micropython.readthedocs.io/en/latest/
66

7-
The documentation you see there is generated from the files in the docs tree:
8-
https://github.com/micropython/micropython/tree/master/docs
7+
The documentation you see there is generated from the files in the whole tree:
8+
https://github.com/adafruit/micropython/tree/master
99

1010
Building the documentation locally
1111
----------------------------------
1212

13-
If you're making changes to the documentation, you may want to build the
13+
If you're making changes to the documentation, you should build the
1414
documentation locally so that you can preview your changes.
1515

1616
Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
@@ -19,22 +19,8 @@ preferably in a virtualenv:
1919
pip install sphinx
2020
pip install sphinx_rtd_theme
2121

22-
In `micropython/docs`, build the docs:
22+
In `micropython/`, build the docs:
2323

24-
make MICROPY_PORT=<port_name> html
24+
sphinx-build -v -b html . _build/html
2525

26-
Where `<port_name>` can be `unix`, `pyboard`, `wipy` or `esp8266`.
27-
28-
You'll find the index page at `micropython/docs/build/<port_name>/html/index.html`.
29-
30-
PDF manual generation
31-
---------------------
32-
33-
This can be achieved with:
34-
35-
make MICROPY_PORT=<port_name> latexpdf
36-
37-
but require rather complete install of LaTeX with various extensions. On
38-
Debian/Ubuntu, try (500MB+ download):
39-
40-
apt-get install texlive-latex-recommended texlive-latex-extra
26+
You'll find the index page at `micropython/docs/_build/html/index.html`.

0 commit comments

Comments
 (0)
0