registro de uso de documentos de escritura de esfinge

1. Instalar el entorno sphinx

Primero instale el entorno python

Anaconda se puede instalar aquí, lo cual es más conveniente de usar. Referencia: instalación de Anaconda e introducción detallada (con gráficos)

Utilizo directamente scoop para instalar aquí.

# 安装 miniconda 
scoop install -g miniconda3

Installing 'miniconda3' (4.7.12.1) [64bit]
Miniconda3-4.7.12.1-Windows-x86_64.exe (51.5 MB) [============================================================] 100%
Checking hash of Miniconda3-4.7.12.1-Windows-x86_64.exe ... ok.
Running installer... done.
Linking C:\scoop\apps\miniconda3\current => C:\scoop\apps\miniconda3\4.7.12.1
Creating shim for 'python'.
Creating shim for 'pythonw'.
Creating shim for 'python3'.
Persisting envs
'miniconda3' (4.7.12.1) was installed successfully!

Luego instale el software Sphinx

Abrir anaconda3propia Anaconda Prompt, introduzca el siguiente comando para instalar

# 安装 Sphinx 本身，这里也可以使用 pip 安装
conda install Sphinx
# 安装 sphinxcontrib-fulltoc 插件
#  Sphinx 默认是不产生侧边栏的Tree 结构的，所以需要插件sphinxcontrib-fulltoc 
pip install sphinxcontrib-fulltoc

2. Generar proyecto Sphinx

Crear un directorio del proyecto, y luego entrar en el directorio, ejecute sphinx-quickstartel comando.

Las opciones se preguntarán a su vez aquí:

• Código fuente separado y directorio de compilación (sí / no)
• Nombre del proyecto: se puede escribir en chino
• Nombre del autor: puede escribir chino
• Lanzamiento de ingeniería: escriba un número de versión. Sphinx tiene un concepto de "versión" y "distribución". Cada versión puede tener múltiples versiones de lanzamiento. Por ejemplo, para Python, la versión es similar a 2.5 o 3.0, y la distribución es similar a 2.5.1 o 3.0a1. Si no se necesita esta estructura dual, simplemente configure ambas en el mismo valor.
• Lenguaje de ingeniería: zh_cn es chino

sphinx-quickstart
Welcome to the Sphinx 2.4.4 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:y

The project name will occur in several places in the built documentation.
> Project name: helpdoc
> Author name(s): solym
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_cn

Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

3. Escribir y construir documentación

Para conocer métodos de escritura específicos, puede consultar: Manual del usuario de Sphinx , reStructuredText Getting Started .

Después de la finalización de la preparación del documento, puede utilizar makeun script para generar el formato de archivo de destino, por ejemplo, para generar htmlsobre la aplicación de make htmlla lata, los ficheros objeto resultante builddirectorio.

make
Sphinx v2.4.4
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)