micropython/docs
Jim Mussared 69e34b6b6b all: Switch to new preview build versioning scheme.
See https://github.com/micropython/micropython/issues/12127 for details.

Previously at the point when a release is made, we update mpconfig.h
and set a git tag. i.e. the version increments at the release.

Now the version increments immediately after the release. The workflow is:
1. Final commit in the cycle updates mpconfig.h to set (X, Y, 0, 0) (i.e.
   clear the pre-release state).
2. This commit is tagged "vX.Y.0".
3. First commit for the new cycle updates mpconfig.h to set (X, Y+1, 0, 1)
   (i.e. increment the minor version, set the pre-release state).
4. This commit is tagged "vX.Y+1.0-preview".

The idea is that a nightly build is actually a "preview" of the _next_
release. i.e. any documentation describing the current release may not
actually match the nightly build. So we use "preview" as our semver
pre-release identifier.

Changes in this commit:
 - Add MICROPY_VERSION_PRERELEASE to mpconfig.h to allow indicating that
   this is not a release version.
 - Remove unused MICROPY_VERSION integer.
 - Append "-preview" to MICROPY_VERSION_STRING when the pre-release state
   is set.
 - Update py/makeversionhdr.py to no longer generate MICROPY_GIT_HASH.
 - Remove the one place MICROPY_GIT_HASH was used (it can use
   MICROPY_GIT_TAG instead).
 - Update py/makeversionhdr.py to also understand
   MICROPY_VERSION_PRERELEASE in mpconfig.h.
 - Update py/makeversionhdr.py to convert the git-describe output into
   semver-compatible "X.Y.Z-preview.N.gHASH".
 - Update autobuild.sh to generate filenames using the new scheme.
 - Update remove_old_firmware.py to match new scheme.
 - Update mpremote's pyproject.toml to handle the "-preview" suffix in the
   tag. setuptools_scm maps to this "rc0" to match PEP440.
 - Fix docs heading where it incorrectly said "vvX.Y.Z" for release docs.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-10-06 12:10:14 +11:00
..
develop docs: Add requirements.txt file with dependencies for Sphinx. 2023-10-02 12:35:12 +11:00
differences
esp32 docs,tools: Change remaining "urequests" references to "requests". 2023-10-05 14:04:45 +11:00
esp8266
library extmod/modnetwork: Increase max hostname length to 32. 2023-10-04 12:39:23 +11:00
mimxrt
pyboard
readthedocs/settings
reference all: Fix various spelling mistakes found by codespell 2.2.6. 2023-10-03 11:24:50 +11:00
renesas-ra docs/library/index: Update docs after umodule rename. 2023-06-08 17:54:28 +10:00
rp2
samd samd/boards: Rename flash pins consistently for QSPI and SPI. 2023-06-06 00:42:33 +10:00
static
templates all: Switch to new preview build versioning scheme. 2023-10-06 12:10:14 +11:00
unix
wipy
zephyr docs/library/index: Update docs after umodule rename. 2023-06-08 17:54:28 +10:00
Makefile
README.md
conf.py all: Switch to new preview build versioning scheme. 2023-10-06 12:10:14 +11:00
index.rst
license.rst
make.bat
requirements.txt docs: Add requirements.txt file with dependencies for Sphinx. 2023-10-02 12:35:12 +11:00

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 html

You'll find the index page at micropython/docs/build/html/index.html.

Having readthedocs.org build the documentation

If you would like to have docs for forks/branches hosted on GitHub, GitLab or BitBucket an alternative to building the docs locally is to sign up for a free https://readthedocs.org account. The rough steps to follow are:

  1. sign-up for an account, unless you already have one
  2. in your account settings: add GitHub as a connected service (assuming you have forked this repo on github)
  3. in your account projects: import your forked/cloned micropython repository into readthedocs
  4. in the project's versions: add the branches you are developing on or for which you'd like readthedocs to auto-generate docs whenever you push a change

PDF manual generation

This can be achieved with:

make latexpdf

but requires a rather complete install of LaTeX with various extensions. On Debian/Ubuntu, try (1GB+ download):

apt install texlive-latex-recommended texlive-latex-extra texlive-xetex texlive-fonts-extra cm-super xindy