Sphinx

https://www.sphinx-doc.org/

Prerequisites

Install python3 and pip3, see Install Python Development Environment.

Install

Edit file requirements.txt:

Sphinx
myst-parser
sphinx-copybutton
sphinx-design
sphinx-rtd-theme
sphinxcontrib-mermaid

Install the requirements:

$ pip3 install -r requirements.txt

Check the version:

$ sphinx-build --version
sphinx-build 8.1.3

Usage

In your working directory:

$ sphinx-quickstart

Edit file conf.py:

 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import sys
+
+sys.path.append('.')
+
+from lasphinx import *
+
 project = "Lasy's Documentation"
-copyright = '2024, Lasy'
+copyright = '%Y, Lasy'
 author = 'Lasy'
+release = 'latest'
+language = 'en'
+html_logo = '_images/lasydoc.png'
+html_favicon = '_images/favicon-96x96.png'
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+myst_substitutions = {
+}
 
-extensions = []
-
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-
+exclude_patterns += ['AGENTS.md']
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
-html_static_path = ['_static']
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'logo_only': True,
+}
+
+html_css_files += ['lasyard_sphinx_rtd_theme.css']

Build html:

$ make html

Then open _build/html/index.html in your browser.

Build pdf

Need latexmk. On macOS, install BasicTex from https://www.tug.org/mactex/morepackages.html. Then install latexmk:

$ sudo tlmgr update --self
$ sudo tlmgr install latexmk

$ latexmk --version
Latexmk, John Collins, 9 March 2026. Version 4.88

Common packages may be needed:

$ sudo tlmgr install tex-gyre collection-fontsrecommended collection-latexrecommended collection-fontsextra

More:

sudo tlmgr install fncychap tabulary capt-of framed needspace wrapfig multirow varwidth cmap upquote parskip titlesec eqparbox environ trimspaces mdframed zref etoolbox tocloft xcolor float wrapfig ucs pict2e ellipse

For CJK characters:

$ sudo tlmgr install xecjk fandol

In your conf.py:

latex_engine = 'xelatex'
latex_elements = {
    'preamble': r'''
\usepackage{xeCJK}
\setCJKmainfont{Source Han Serif CN VF} # 思源宋体
''',
}

Need mmdc to convert mermaid graph:

$ PUPPETEER_SKIP_DOWNLOAD=true npm install -g --allow-scripts=puppeteer @mermaid-js/mermaid-cli

Set PUPPETEER_SKIP_DOWNLOAD=true to skip downloading Chromium for we can use the existing Chrome (if there is). Need a config file:

{
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

Put the file to ~/.config/puppeteer-config.json. Set mmdc command in conf.py:

mermaid_cmd = "/Users/jyg/.nvm/versions/node/v24.18.0/bin/mmdc"
mermaid_params = ["-p", "/Users/jyg/puppeteer-config.json"]