About#

本文档的生成方法:

conda create -n note Sphinx
conda activate note
pip install --upgrade myst-parser
pip install pydata-sphinx-theme
pip install sphinx-autobuild
pip install nbsphinx

How to Use Markdown#

Markdown is a lightweight markup language with a simplistic plain text formatting syntax. It exists in many syntactically different flavors. To support Markdown-based documentation, Sphinx can use MyST-Parser. MyST-Parser is a Docutils bridge to markdown-it-py, a Python package for parsing the CommonMark Markdown flavor.

Configuration#

To configure your Sphinx project for Markdown support, proceed as follows:

  1. Install the Markdown parser MyST-Parser:

pip install --upgrade myst-parser

  1. Add myst_parser to the extensions configuration option:

extensions = ['myst_parser']

Note

MyST-Parser requires Sphinx 2.1 or newer.

  1. If you want to use Markdown files with extensions other than .md, adjust the source_suffix variable. The following example configures Sphinx to parse all files with the extensions .md and .txt as Markdown:

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

  1. You can further configure MyST-Parser to allow custom syntax that standard CommonMark doesn’t support. Read more in the MyST-Parser documentation.

pydata-sphinx-theme#

Home Page: https://github.com/pydata/pydata-sphinx-theme

The theme is available on PyPI and conda-forge. You can install and use as follows:

  1. Install the pydata-sphinx-theme in your doc build environment:

    pip install pydata-sphinx-theme
# or
conda install pydata-sphinx-theme --channel conda-forge

  2. Then, in the conf.py of your sphinx docs, you update the html_theme configuration option:

    html_theme = "pydata_sphinx_theme"

sphinx-autobuild#

Homepage: https://github.com/executablebooks/sphinx-autobuild

Rebuild Sphinx documentation on changes, with live-reload in the browser.

Installation#

sphinx-autobuild is available on PyPI. It can be installed using pip:

pip install sphinx-autobuild

Usage#

To build a classical Sphinx documentation set, run:

sphinx-autobuild docs docs/_build/html

This will start a server at http://127.0.0.1:8000 and start watching for changes in the docs/ directory. When a change is detected in docs/, the documentation is rebuilt and any open browser windows are reloaded automatically. KeyboardInterrupt (ctrl+c) will stop the server.

Using with Makefile

FYI: Sphinx is planning to move away from using Makefile.

To use sphinx-autobuild with the Makefile generated by Sphinx, add the following to the end of the Makefile:

live:
    sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Then use command to make live documentation:

make live

requirements.txt#

pip freeze > requirements.txt
pip install -r path\to\requirements.txt
pip install -i https://pypi.doubanio.com/simple -r path\to\requirements.txt

readthedocs#

Read the Docs supports configuring your documentation builds with a YAML file. The configuration file must be in the root directory of your project and be named .readthedocs.yaml. For example:

# .readthedocs.yaml
# should be put in the root of
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
os: ubuntu-20.04
tools:
    python: "3.9"
    # You can also specify other tool versions:
    # nodejs: "16"
    # rust: "1.55"
    # golang: "1.17"

# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py

# If using Sphinx, optionally build your docs in additional formats such as PDF
# formats:
#    - pdf

# Optionally declare the Python requirements required to build your docs
python:
install:
- requirements: docs/requirements.txt

Jupyter Notebook Tools for Sphinx#

nbsphinx is a Sphinx extension that provides a source parser for *.ipynb files. Custom Sphinx directives are used to show Jupyter Notebook code cells (and of course their results) in both HTML and LaTeX output. Un-evaluated notebooks – i.e. notebooks without stored output cells – will be automatically executed during the Sphinx build process.

Quick Start:

  1. Install nbsphinx

  2. Edit your conf.py and add ‘nbsphinx’ to extensions:

    extensions = [
    'nbsphinx',
]

  3. Edit your index.rst and add the names of your *.ipynb files to the toctree.

  4. Run Sphinx!

Online documentation (and example of use): https://nbsphinx.readthedocs.io/

Source code repository (and issue tracker): https://github.com/spatialaudio/nbsphinx/

Issue#

There is a issue:No Pygments lexer found for “ipython3”.

see: https://github.com/jupyter/nbconvert/issues/528

Why: the ipython in conda is not work.

How to fix: use pip install ipython in venv of the projcet.

previous

【Python茴香豆系列】之 字典合并