b7fa63c7ce
This patch introduces the a small framework to track differences between uPy and CPython. The framework consists of: - A set of "tests" which test for an individual feature that differs between uPy and CPy. Each test is like a normal uPy test in the test suite, but has a special comment at the start with some meta-data: a category (eg syntax, core language), a human-readable description of the difference, a cause, and a workaround. Following the meta-data there is a short code snippet which demonstrates the difference. See tests/cpydiff directory for the initial set of tests. - A program (this patch) which runs all the tests (on uPy and CPy) and generates nicely-formated .rst documenting the differences. - Integration into the docs build so that everything is automatic, and the differences appear in a way that is easy for users to read/reference (see latter commits). The idea with using this new framework is: - When a new difference is found it's easy to write a short test for it, along with a description, and add it to the existing ones. It's also easy for contributors to submit tests for differences they find. - When something is no longer different the tool will give an error and difference can be removed (or promoted to a proper feature test). |
||
|---|---|---|
| .. | ||
| differences | ||
| esp8266 | ||
| library | ||
| pyboard | ||
| readthedocs/settings | ||
| reference | ||
| sphinx_selective_exclude | ||
| static | ||
| templates | ||
| wipy | ||
| Makefile | ||
| README.md | ||
| conf.py | ||
| esp8266_contents.rst | ||
| esp8266_index.rst | ||
| license.rst | ||
| make.bat | ||
| pyboard_contents.rst | ||
| pyboard_index.rst | ||
| topindex.html | ||
| unix_contents.rst | ||
| unix_index.rst | ||
| wipy_contents.rst | ||
| wipy_index.rst | ||
README.md
MicroPython Documentation
The MicroPython documentation can be found at: http://docs.micropython.org/en/latest/
The documentation you see there is generated from the files in the docs tree: https://github.com/micropython/micropython/tree/master/docs
Building the documentation locally
If you're making changes to the documentation, you may want to build the documentation locally so that you can preview your changes.
Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme, preferably in a virtualenv:
pip install sphinx
pip install sphinx_rtd_theme
In micropython/docs, build the docs:
make MICROPY_PORT=<port_name> html
Where <port_name> can be unix, pyboard, wipy or esp8266.
You'll find the index page at micropython/docs/build/<port_name>/html/index.html.
PDF manual generation
This can be achieved with:
make MICROPY_PORT=<port_name> latexpdf
but require rather complete install of LaTeX with various extensions. On Debian/Ubuntu, try (500MB+ download):
apt-get install texlive-latex-recommended texlive-latex-extra