如何写项目文档--Document!

于 2023-09-07 15:31:31 发布
阅读量355 收藏 3
点赞数 3
文章标签： java 开发语言
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/weixin_52943021/article/details/132735765
版权

项目环境：Window11

提前准备的环境：Python3.10.11    anaconda3

创建虚拟环境

(base) PS C:\Users\lcds\pro\vue3-project> conda create -n document python=3.10
Collecting package metadata (current_repodata.json): done
Solving environment: done


==> WARNING: A newer version of conda exists. <==
  current version: 23.5.0
  latest version: 23.7.3

Please update conda by running

    $ conda update -n base -c defaults conda

Or to minimize the number of packages updated during conda update use

     conda install conda=23.7.3



## Package Plan ##

  environment location: C:\users\lcds\anaconda3\envs\document

  added / updated specs:
    - python=3.10


The following NEW packages will be INSTALLED:

  bzip2              pkgs/main/win-64::bzip2-1.0.8-he774522_0
  ca-certificates    pkgs/main/win-64::ca-certificates-2023.05.30-haa95532_0
  libffi             pkgs/main/win-64::libffi-3.4.4-hd77b12b_0
  openssl            pkgs/main/win-64::openssl-3.0.10-h2bbff1b_2
  pip                pkgs/main/win-64::pip-23.2.1-py310haa95532_0
  python             pkgs/main/win-64::python-3.10.12-he1021f5_0
  setuptools         pkgs/main/win-64::setuptools-68.0.0-py310haa95532_0
  sqlite             pkgs/main/win-64::sqlite-3.41.2-h2bbff1b_0
  tk                 pkgs/main/win-64::tk-8.6.12-h2bbff1b_0
  tzdata             pkgs/main/noarch::tzdata-2023c-h04d1e81_0
  vc                 pkgs/main/win-64::vc-14.2-h21ff451_1
  vs2015_runtime     pkgs/main/win-64::vs2015_runtime-14.27.29016-h5e58377_2
  wheel              pkgs/main/win-64::wheel-0.38.4-py310haa95532_0
  xz                 pkgs/main/win-64::xz-5.4.2-h8cc25b3_0
  zlib               pkgs/main/win-64::zlib-1.2.13-h8cc25b3_0


Proceed ([y]/n)? y


Downloading and Extracting Packages

Preparing transaction: done
Verifying transaction: done
Executing transaction: done
#
# To activate this environment, use
#
#     $ conda activate document
#
# To deactivate an active environment, use
#
#     $ conda deactivate

(base) PS C:\Users\lcds\pro\vue3-project>

查看当前已经安装的python环境 conda env list 和 conda info --env 都是查看当前已经有的虚拟环境  两种查询方式如下

PS C:\Users\lcds\pro\vue3-project> conda env list
# conda environments:
#
                         C:\Users\lcds\anaconda3
base                     C:\users\lcds\anaconda3
chatgpt                  C:\users\lcds\anaconda3\envs\chatgpt
wtd                      C:\users\lcds\anaconda3\envs\wtd

-------------------------------------------------------------------------------------------

PS C:\Users\lcds\pro\vue3-project> conda info --env
# conda environments:
#
                         C:\Users\lcds\anaconda3
base                     C:\users\lcds\anaconda3
chatgpt                  C:\users\lcds\anaconda3\envs\chatgpt
wtd                      C:\users\lcds\anaconda3\envs\wtd

base是anaconda自带的一个环境，其余是自己安装的虚拟环境

激活虚拟环境

(base) PS C:\Users\lcds\pro\vue3-project> conda activate document
(document) PS C:\Users\lcds\pro\vue3-project>

在当前目录下创建document/docs文件夹 并进入该文件夹

(document) PS C:\Users\lcds\pro\vue3-project\document> mkdir document

(document) PS C:\Users\lcds\pro\vue3-project> cd document
(document) PS C:\Users\lcds\pro\vue3-project\document> 

(document) PS C:\Users\lcds\pro\vue3-project\document> mkdir docs

document) PS C:\Users\lcds\pro\vue3-project\document> cd docs
(document) PS C:\Users\lcds\pro\vue3-project\document\docs>

安装Sphinx,并启动项目默认文档模板

(document) PS C:\Users\lcds\pro\vue3-project\document\docs>pip install sphinx


(document) PS C:\Users\lcds\pro\vue3-project\document\docs> sphinx-quickstart
Welcome to the Sphinx 7.0.1 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.
# 有两种方式来设置 Sphinx 输出的创建目录：
# 一是在根路径下创建"_build" 目录，二是在根路径下创建"source" 和 "build"两个独立的目录。
> Separate source and build directories (y/n) [n]: y
# 独立的源文件和构建目录(y/n) [n]

The project name will occur in several places in the built documentation.
# 项目名称将会出现在文档的许多地方。
> Project name: vue3-project  # 项目名称：
> Author name(s): mary		# 作者名称：
> Project release []: 0.0.1		# 项目发行版本【】：

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.
# 如果用英语以外的语言编写文档。
# 你可以在此按语言代码选择语种。
# Sphinx 会把内置文件翻译成相应语言的版本.

For a list of supported codes, see
# 支持的语言代码列表见：
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN   # 项目语种[en]

# 创建文件
Creating file C:\Users\lcds\pro\vue3-project\document\docs\source\conf.py.
Creating file C:\Users\lcds\pro\vue3-project\document\docs\source\index.rst.
Creating file C:\Users\lcds\pro\vue3-project\document\docs\Makefile.
Creating file C:\Users\lcds\pro\vue3-project\document\docs\make.bat.


Finished: An initial directory structure has been created.
# 完成：已创建初始目录结构

You should now populate your master file C:\Users\lcds\pro\vue3-project\document\docs\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.
# 你现在可以填写文档文件：C:\Users\lcds\pro\vue3-project\document\docs\source\index.rst
# 并创建其他文档源文件了。用 Makefile 构建文件。例如： make builder
# 此处的"builder" 是支持的构建器名，比如 html,latex 或者 linkcheck

(document) PS C:\Users\lcds\pro\vue3-project\document\docs>

生成网页版文档

(base) PS C:\Users\lcds\pro\vue3-project\document\docs> make html
Running Sphinx v7.0.1
loading translations [zh_CN]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.
(base) PS C:\Users\lcds\pro\vue3-project\document\docs>

生成网页版文档 目录解释

_build: 所有输出的文件都放在该文件夹里面

_static:主要是些关于css或者JavaScript的一些脚本

_templates: 主要放一些模板文件，网页版本的布局就是这个文件来指定的

conf.py: 配置文件，主要是用来配置一些设置

index.rst: 相当于是一个网站，登录页面，PDF，网站的入口

make.bat: 主要是针对Window下一些简单命令来实现 make 命令缩写 是window 批处理命令文件

Makefile: 这个是执行 make 命令 ，比如 make html   make clean等

按 Shift+ Alt+R 快捷键 找到file:///C:/Users/lcds/pro/vue3-project/document/docs/build/html/index.html(找到_build目录下HTML文件夹下的 index.html,鼠标右键，找到资源文件  有Shift+Alt+R 快捷键那行，点击进去， 在资源文档看到 index,双击进去就可以了)

index.html 双击打开如下图所示

安装 furo   furo是一个可以自定义的文档主题，他对我们非常友好，furo支持手机和平板 PC端，效果比较好。Sphinx内置库没有，所以我们要安装它

(document) PS C:\Users\lcds\pro\vue3-project\document\docs> pip install furo
Collecting furo
  Obtaining dependency information for furo from https://files.pythonhosted.org/packages/cb/7e/7af529e3fc72d4e2b7ec228027c21049126994af28a21b0c1d6198e84ef1/furo-2023.8.19-py3-none-any.whl.metadata
  Downloading furo-2023.8.19-py3-none-any.whl.metadata (5.9 kB)
Collecting beautifulsoup4 (from furo)
  Downloading beautifulsoup4-4.12.2-py3-none-any.whl (142 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 143.0/143.0 kB 90.4 kB/s eta 0:00:00
Collecting sphinx<8.0,>=6.0 (from furo)
  Obtaining dependency information for sphinx<8.0,>=6.0 from https://files.pythonhosted.org/packages/a6/54/f4fcf7113eb051a46476ecce9485c463f58dbc3887c06dbfe1e67a8ce7c0/sphinx-7.2.5-py3-none-any.whl.metadata
  Downloading sphinx-7.2.5-py3-none-any.whl.metadata (5.9 kB)
Collecting sphinx-basic-ng (from furo)
  Obtaining dependency information for sphinx-basic-ng from https://files.pythonhosted.org/packages/3c/dd/018ce05c532a22007ac58d4f45232514cd9d6dd0ee1dc374e309db830983/sphinx_basic_ng-1.0.0b2-py3-none-any.whl.metadata
  Downloading sphinx_basic_ng-1.0.0b2-py3-none-any.whl.metadata (1.5 kB)
Collecting pygments>=2.7 (from furo)
  Obtaining dependency information for pygments>=2.7 from https://files.pythonhosted.org/packages/43/88/29adf0b44ba6ac85045e63734ae0997d3c58d8b1a91c914d240828d0d73d/Pygments-2.16.1-py3-none-any.whl.metadata
  Downloading Pygments-2.16.1-py3-none-any.whl.metadata (2.5 kB)
Collecting sphinxcontrib-applehelp (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for sphinxcontrib-applehelp from https://files.pythonhosted.org/packages/c0/0c/261c0949083c0ac635853528bb0070c89e927841d4e533ba0b5563365c06/sphinxcontrib_applehelp-1.0.7-py3-none-any.whl.metadata
  Downloading sphinxcontrib_applehelp-1.0.7-py3-none-any.whl.metadata (2.2 kB)
Collecting sphinxcontrib-devhelp (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for sphinxcontrib-devhelp from https://files.pythonhosted.org/packages/c0/03/010ac733ec7b7f71c1dc88e7115743ee466560d6d85373b56fb9916e4586/sphinxcontrib_devhelp-1.0.5-py3-none-any.whl.metadata
  Downloading sphinxcontrib_devhelp-1.0.5-py3-none-any.whl.metadata (2.2 kB)
Collecting sphinxcontrib-jsmath (from sphinx<8.0,>=6.0->furo)
  Using cached sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl (5.1 kB)
Collecting sphinxcontrib-htmlhelp>=2.0.0 (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for sphinxcontrib-htmlhelp>=2.0.0 from https://files.pythonhosted.org/packages/28/7a/958f8e3e6abe8219d0d1f1224886de847ab227b218f4a07b61bc337f64be/sphinxcontrib_htmlhelp-2.0.4-py3-none-any.whl.metadata
  Downloading sphinxcontrib_htmlhelp-2.0.4-py3-none-any.whl.metadata (2.2 kB)
Collecting sphinxcontrib-serializinghtml>=1.1.9 (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for sphinxcontrib-serializinghtml>=1.1.9 from https://files.pythonhosted.org/packages/95/d6/2e0bda62b2a808070ac922d21a950aa2cb5e4fcfb87e5ff5f86bc43a2201/sphinxcontrib_serializinghtml-1.1.9-py3-none-any.whl.metadata
  Downloading sphinxcontrib_serializinghtml-1.1.9-py3-none-any.whl.metadata (2.3 kB)
Collecting sphinxcontrib-qthelp (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for sphinxcontrib-qthelp from https://files.pythonhosted.org/packages/1f/e5/1850f3f118e95581c1e30b57028ac979badee1eb29e70ee72b0241f5a185/sphinxcontrib_qthelp-1.0.6-py3-none-any.whl.metadata
  Downloading sphinxcontrib_qthelp-1.0.6-py3-none-any.whl.metadata (2.2 kB)
Collecting Jinja2>=3.0 (from sphinx<8.0,>=6.0->furo)
  Downloading Jinja2-3.1.2-py3-none-any.whl (133 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 133.1/133.1 kB 36.6 kB/s eta 0:00:00
Collecting docutils<0.21,>=0.18.1 (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for docutils<0.21,>=0.18.1 from https://files.pythonhosted.org/packages/26/87/f238c0670b94533ac0353a4e2a1a771a0cc73277b88bff23d3ae35a256c1/docutils-0.20.1-py3-none-any.whl.metadata
  Downloading docutils-0.20.1-py3-none-any.whl.metadata (2.8 kB)
Collecting snowballstemmer>=2.0 (from sphinx<8.0,>=6.0->furo)
  Using cached snowballstemmer-2.2.0-py2.py3-none-any.whl (93 kB)
Collecting babel>=2.9 (from sphinx<8.0,>=6.0->furo)
  Downloading Babel-2.12.1-py3-none-any.whl (10.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 10.1/10.1 MB 37.2 kB/s eta 0:00:00
Collecting alabaster<0.8,>=0.7 (from sphinx<8.0,>=6.0->furo)
  Using cached alabaster-0.7.13-py3-none-any.whl (13 kB)
Collecting imagesize>=1.3 (from sphinx<8.0,>=6.0->furo)
  Using cached imagesize-1.4.1-py2.py3-none-any.whl (8.8 kB)
Collecting requests>=2.25.0 (from sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for requests>=2.25.0 from https://files.pythonhosted.org/packages/70/8e/0e2d847013cb52cd35b38c009bb167a1a26b2ce6cd6965bf26b47bc0bf44/requests-2.31.0-py3-none-any.whl.metadata
  Downloading requests-2.31.0-py3-none-any.whl.metadata (4.6 kB)
Collecting packaging>=21.0 (from sphinx<8.0,>=6.0->furo)
  Downloading packaging-23.1-py3-none-any.whl (48 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 48.9/48.9 kB 44.2 kB/s eta 0:00:00
Collecting colorama>=0.4.5 (from sphinx<8.0,>=6.0->furo)
  Downloading colorama-0.4.6-py2.py3-none-any.whl (25 kB)
Collecting soupsieve>1.2 (from beautifulsoup4->furo)
  Obtaining dependency information for soupsieve>1.2 from https://files.pythonhosted.org/packages/4c/f3/038b302fdfbe3be7da016777069f26ceefe11a681055ea1f7817546508e3/soupsieve-2.5-py3-none-any.whl.metadata
  Downloading soupsieve-2.5-py3-none-any.whl.metadata (4.7 kB)
Collecting MarkupSafe>=2.0 (from Jinja2>=3.0->sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for MarkupSafe>=2.0 from https://files.pythonhosted.org/packages/84/a8/c4aebb8a14a1d39d5135eb8233a0b95831cdc42c4088358449c3ed657044/MarkupSafe-2.1.3-cp310-cp310-win_amd64.whl.metadata
  Downloading MarkupSafe-2.1.3-cp310-cp310-win_amd64.whl.metadata (3.1 kB)
Collecting charset-normalizer<4,>=2 (from requests>=2.25.0->sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for charset-normalizer<4,>=2 from https://files.pythonhosted.org/packages/5c/f2/f3faa20684729d3910af2ee142e30432c7a46a817eadeeab87366ed87bbb/charset_normalizer-3.2.0-cp310-cp310-win_amd64.whl.metadata
  Downloading charset_normalizer-3.2.0-cp310-cp310-win_amd64.whl.metadata (31 kB)
Collecting idna<4,>=2.5 (from requests>=2.25.0->sphinx<8.0,>=6.0->furo)
  Downloading idna-3.4-py3-none-any.whl (61 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 61.5/61.5 kB 91.1 kB/s eta 0:00:00
Collecting urllib3<3,>=1.21.1 (from requests>=2.25.0->sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for urllib3<3,>=1.21.1 from https://files.pythonhosted.org/packages/9b/81/62fd61001fa4b9d0df6e31d47ff49cfa9de4af03adecf339c7bc30656b37/urllib3-2.0.4-py3-none-any.whl.metadata
  Downloading urllib3-2.0.4-py3-none-any.whl.metadata (6.6 kB)
Collecting certifi>=2017.4.17 (from requests>=2.25.0->sphinx<8.0,>=6.0->furo)
  Obtaining dependency information for certifi>=2017.4.17 from https://files.pythonhosted.org/packages/4c/dd/2234eab22353ffc7d94e8d13177aaa050113286e93e7b40eae01fbf7c3d9/certifi-2023.7.22-py3-none-any.whl.metadata
  Downloading certifi-2023.7.22-py3-none-any.whl.metadata (2.2 kB)
Using cached furo-2023.8.19-py3-none-any.whl (323 kB)
Downloading Pygments-2.16.1-py3-none-any.whl (1.2 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.2/1.2 MB 38.9 kB/s eta 0:00:00
Downloading sphinx-7.2.5-py3-none-any.whl (3.2 MB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.2/3.2 MB 34.3 kB/s eta 0:00:00
Using cached sphinx_basic_ng-1.0.0b2-py3-none-any.whl (22 kB)
Using cached docutils-0.20.1-py3-none-any.whl (572 kB)
Downloading requests-2.31.0-py3-none-any.whl (62 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 62.6/62.6 kB 23.3 kB/s eta 0:00:00
Downloading soupsieve-2.5-py3-none-any.whl (36 kB)
Downloading sphinxcontrib_htmlhelp-2.0.4-py3-none-any.whl (99 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 99.2/99.2 kB 33.3 kB/s eta 0:00:00
Downloading sphinxcontrib_serializinghtml-1.1.9-py3-none-any.whl (92 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 92.7/92.7 kB 30.9 kB/s eta 0:00:00
Downloading sphinxcontrib_applehelp-1.0.7-py3-none-any.whl (120 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 120.0/120.0 kB 42.6 kB/s eta 0:00:00
Downloading sphinxcontrib_devhelp-1.0.5-py3-none-any.whl (83 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 83.5/83.5 kB 35.2 kB/s eta 0:00:00
Downloading sphinxcontrib_qthelp-1.0.6-py3-none-any.whl (89 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 89.4/89.4 kB 32.3 kB/s eta 0:00:00
Downloading certifi-2023.7.22-py3-none-any.whl (158 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 158.3/158.3 kB 31.6 kB/s eta 0:00:00
Downloading charset_normalizer-3.2.0-cp310-cp310-win_amd64.whl (96 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 96.9/96.9 kB 26.7 kB/s eta 0:00:00
Downloading MarkupSafe-2.1.3-cp310-cp310-win_amd64.whl (17 kB)
Downloading urllib3-2.0.4-py3-none-any.whl (123 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 123.9/123.9 kB 40.6 kB/s eta 0:00:00
Installing collected packages: snowballstemmer, urllib3, sphinxcontrib-jsmath, soupsieve, pygments, packaging, MarkupSafe, imagesize, idna, docutils, colorama, charset-normalizer, certifi, babel, alabaster, requests, Jinja2, beautifulsoup4, sphinxcontrib-serializinghtml, sphinxcontrib-qthelp, sphinxcontrib-htmlhelp, sphinxcontrib-devhelp, sphinxcontrib-applehelp, sphinx, sphinx-basic-ng, furo
Successfully installed Jinja2-3.1.2 MarkupSafe-2.1.3 alabaster-0.7.13 babel-2.12.1 beautifulsoup4-4.12.2 certifi-2023.7.22 charset-normalizer-3.2.0 colorama-0.4.6 docutils-0.20.1 furo-2023.8.19 idna-3.4 imagesize-1.4.1 packaging-23.1 pygments-2.16.1 requests-2.31.0 snowballstemmer-2.2.0 soupsieve-2.5 sphinx-7.2.5 sphinx-basic-ng-1.0.0b2 sphinxcontrib-applehelp-1.0.7 sphinxcontrib-devhelp-1.0.5 sphinxcontrib-htmlhelp-2.0.4 sphinxcontrib-jsmath-1.0.1 sphinxcontrib-qthelp-1.0.6 sphinxcontrib-serializinghtml-1.1.9 urllib3-2.0.4
(document) PS C:\Users\lcds\pro\vue3-project\document\docs>

修改配置文件 conf.py 把 html_theme = 'alabaster' 修改为 html_theme = 'furo'

# html_theme = 'alabaster'  
html_theme = 'furo'

再次清理，再次构建html

(document) PS C:\Users\lcds\pro\vue3-project\document\docs> make clean

(document) PS C:\Users\lcds\pro\vue3-project\document\docs> make html
Running Sphinx v7.2.5
loading translations [zh_CN]... done
loading pickled environment... failed: build environment version not current
done
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

找到 index.html 右键 找 到有'Shift+Alt+R'即资源管理器点击进去。可以看到 index.html 双击，在浏览器中打开，如下图所示：（直接在浏览器刷新也可以）

创建子目录(如何启动index) start/index.rst

(document) PS C:\Users\lcds\pro\vue3-project\document\docs>mkdir start


(document) PS C:\Users\lcds\pro\vue3-project\document\docs>cd start


在 start 目录下 创建 index.rst 文件 即子目录的入口文件

index.rst 内容如下：

.. vue3-project documentation master file, created by
   sphinx-quickstart on Wed Sep  6 14:39:34 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

欢迎进入 vue3-project's 文档!
========================================

.. toctree::
   :maxdepth: 2
   :caption: 导航:

   about
   start/index
   

   



索引和表格
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

在 source 目录下创建 about.rst 文件 内容如下

关于
===========


回购担保的反馈疗法


adapt
-----------

sds
-----------


hjdk
*************

在 start 目录下创建 01_conf.rst 文件 内容如下

配置
=============

在 start 目录下创建 02_install.rst 文件 内容如下

安装
=============

在 start 目录下创建 03_ss.md 文件 内容如下

# 会尽快看看

九龙一风

## License


### features
呵呵

要为Sphinx项目配置Markdown支持，请执行以下操作：

  1. 安装 Markdown 解析器 MyST-Parser：



pip install --upgrade myst-parser

(document) PS C:\Users\lcds\pro\vue3-project\document\docs> pip install --upgrade myst-parser
Collecting myst-parser
  Obtaining dependency information for myst-parser from https://files.pythonhosted.org/packages/1d/f6/6d61a023d758f488e36638076e8a4ec4447a2cdf86938cf6c60cf1c860e6/myst_parser-2.0.0-py3-none-any.whl.metadata
  WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'ReadTimeoutError("HTTPSConnectionPool(host='files.pythonhosted.org', port=443): Read timed out. (read timeout=15)")': /packages/1d/f6/6d61a023d758f488e36638076e8a4ec4447a2cdf86938cf6c60cf1c860e6/myst_parser-2.0.0-py3-none-any.whl.metadata
  Downloading myst_parser-2.0.0-py3-none-any.whl.metadata (5.4 kB)
Requirement already satisfied: docutils<0.21,>=0.16 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from myst-parser) (0.20.1)
Requirement already satisfied: jinja2 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from myst-parser) (3.1.2)
Collecting markdown-it-py~=3.0 (from myst-parser)
  Obtaining dependency information for markdown-it-py~=3.0 from https://files.pythonhosted.org/packages/42/d7/1ec15b46af6af88f19b8e5ffea08fa375d433c998b8a7639e76935c14f1f/markdown_it_py-3.0.0-py3-none-any.whl.metadata
  Downloading markdown_it_py-3.0.0-py3-none-any.whl.metadata (6.9 kB)
Collecting mdit-py-plugins~=0.4 (from myst-parser)
  Obtaining dependency information for mdit-py-plugins~=0.4 from https://files.pythonhosted.org/packages/e5/3c/fe85f19699a7b40c8f9ce8ecee7e269b9b3c94099306df6f9891bdefeedd/mdit_py_plugins-0.4.0-py3-none-any.whl.metadata
  Downloading mdit_py_plugins-0.4.0-py3-none-any.whl.metadata (2.7 kB)
Collecting pyyaml (from myst-parser)
  Obtaining dependency information for pyyaml from https://files.pythonhosted.org/packages/24/97/9b59b43431f98d01806b288532da38099cc6f2fea0f3d712e21e269c0279/PyYAML-6.0.1-cp310-cp310-win_amd64.whl.metadata
  Downloading PyYAML-6.0.1-cp310-cp310-win_amd64.whl.metadata (2.1 kB)
Requirement already satisfied: sphinx<8,>=6 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from myst-parser) (7.2.5)
Collecting mdurl~=0.1 (from markdown-it-py~=3.0->myst-parser)
  Downloading mdurl-0.1.2-py3-none-any.whl (10.0 kB)
Requirement already satisfied: sphinxcontrib-applehelp in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (1.0.7)
Requirement already satisfied: sphinxcontrib-devhelp in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (1.0.5)
Requirement already satisfied: sphinxcontrib-jsmath in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (1.0.1)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (2.0.4)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.9 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (1.1.9)
Requirement already satisfied: sphinxcontrib-qthelp in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (1.0.6)
Requirement already satisfied: Pygments>=2.14 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (2.16.1)
Requirement already satisfied: snowballstemmer>=2.0 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (2.2.0)
Requirement already satisfied: babel>=2.9 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (2.12.1)
Requirement already satisfied: alabaster<0.8,>=0.7 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (0.7.13)
Requirement already satisfied: imagesize>=1.3 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (1.4.1)
Requirement already satisfied: requests>=2.25.0 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (2.31.0)
Requirement already satisfied: packaging>=21.0 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (23.1)
Requirement already satisfied: colorama>=0.4.5 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from sphinx<8,>=6->myst-parser) (0.4.6)
Requirement already satisfied: MarkupSafe>=2.0 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from jinja2->myst-parser) (2.1.3)
Requirement already satisfied: charset-normalizer<4,>=2 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from requests>=2.25.0->sphinx<8,>=6->myst-parser) (3.2.0)
Requirement already satisfied: idna<4,>=2.5 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from requests>=2.25.0->sphinx<8,>=6->myst-parser) (3.4)
Requirement already satisfied: urllib3<3,>=1.21.1 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from requests>=2.25.0->sphinx<8,>=6->myst-parser) (2.0.4)
Requirement already satisfied: certifi>=2017.4.17 in c:\users\lcds\anaconda3\envs\document\lib\site-packages (from requests>=2.25.0->sphinx<8,>=6->myst-parser) (2023.7.22)
Downloading myst_parser-2.0.0-py3-none-any.whl (77 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 77.2/77.2 kB 2.8 kB/s eta 0:00:00
Downloading markdown_it_py-3.0.0-py3-none-any.whl (87 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 87.5/87.5 kB 17.7 kB/s eta 0:00:00
Downloading mdit_py_plugins-0.4.0-py3-none-any.whl (54 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 54.1/54.1 kB 22.3 kB/s eta 0:00:00
Downloading PyYAML-6.0.1-cp310-cp310-win_amd64.whl (145 kB)
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 145.3/145.3 kB 16.5 kB/s eta 0:00:00
Installing collected packages: pyyaml, mdurl, markdown-it-py, mdit-py-plugins, myst-parser
Successfully installed markdown-it-py-3.0.0 mdit-py-plugins-0.4.0 mdurl-0.1.2 myst-parser-2.0.0 pyyaml-6.0.1

将myst_parser添加到：

extensions = ['myst_parser']

如果要使用扩展名不是 的 Markdown 文件，请调整 变量。以下示例配置Sphinx解析所有带有扩展名的文件，并作为 ：.md.md.txt

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

配置文件 conf.py的完整代码如下：

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'vue3-project'
copyright = '2023, mary'
author = 'mary'
release = '0.0.1'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = ['myst_parser']

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

templates_path = ['_templates']
exclude_patterns = ['_templates']

language = 'zh_CN'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output


# html_theme = 'alabaster'
html_theme = 'furo'
html_static_path = ['_static']

source/index.rst的完整代码如下：

.. vue3-project documentation master file, created by
   sphinx-quickstart on Wed Sep  6 14:39:34 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

欢迎进入 vue3-project's 文档!
========================================

.. toctree::
   :maxdepth: 2
   :caption: 导航:

   about
   start/index
   

   



索引和表格
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

再次清理再次构建

(document) PS C:\Users\lcds\pro\vue3-project\document\docs> make clean 
Removing everything under 'build'...
(document) PS C:\Users\lcds\pro\vue3-project\document\docs> make html
Running Sphinx v7.2.5
loading translations [zh_CN]... done
making output directory... done
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 6 source files that are out of date
updating environment: [new config] 6 added, 0 changed, 0 removed
reading sources... [100%] start/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] start/index
generating indices... genindex done
writing additional pages... search done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.
(document) PS C:\Users\lcds\pro\vue3-project\document\docs>

win+Shift+S win11窗口截屏如下

再次创建三级子目录 start/update/index.rst    index.rst内容如下

update
================================================================


.. toctree::
    :maxdepth: 2

    01_install
    02_conf
    03_delete
    04_ssdd

在 start/update/ 分别创建了 01_install.rst   02_conf.rst   03_delete.rst   04_ssdd.md四个文见

并且把 start/update/index 添加到 source/index.rst 文件中  具体如下：

.. vue3-project documentation master file, created by
   sphinx-quickstart on Wed Sep  6 14:39:34 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

欢迎进入 vue3-project's 文档!
========================================

.. toctree::
   :maxdepth: 2
   :caption: 导航:

   about
   start/index
   start/update/index

再次清理再次构建

The HTML pages are in build\html.
(document) PS C:\Users\lcds\pro\vue3-project\document\docs> make clean
Removing everything under 'build'...
(document) PS C:\Users\lcds\pro\vue3-project\document\docs> make html
Running Sphinx v7.2.5
loading translations [zh_CN]... done
making output directory... done
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] start/update/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] start/update/index
generating indices... genindex done
writing additional pages... search done
dumping search index in Chinese (code: zh)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

再次刷新浏览器，如下图所示：

下面是一个纯英语版本的三级目录文档 构建代码如下：

wtd) PS C:\Users\lcds\pro\demo\wtd\docs> make html
Running Sphinx v7.2.5
loading pickled environment... done
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources... 
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in _build\html.
(wtd) PS C:\Users\lcds\pro\demo\wtd\docs>

如图所示：

文档构建已接近尾声。

哆啦A梦1588
关注
  • 3
    点赞
  • 踩
  • 3
    收藏
    觉得还不错? 一键收藏
  • 1
    评论
如何给一个GUI软件写document？ Sphinx
Kp0fS的草稿纸
04-03 345
如何给一个GUI软件写document？ how to write the document for a GUI software 如何给Python项目写文档？ 有两种方案： 1、pydoc 不推荐 2、Sphinx （1）pip install sphinx （2）pip install sphinx_rtd_theme test1.py # -*-coding:utf-8-*- class Test1(): ''' 我是测试类，负责测试 '''
iText中文教程~ 创建一个Document
最新发布
小强快跑~~
09-05 388
第一步 创建一个Document实例。第二步 创建Writer实例。第三步 打开Document。第五步 关闭document。
记录安装pytorch时的一个报错
gimlet_的博客
08-01 1569
更改了condarc文件后执行conda claen -i，再继续安装包的时候发现原本只剩1.96g的包又变成了2.14g，但是奇怪的是用everything搜了一个小包，还在，并没有被删去，不过用pip list没有显示昨天已经安装的包；并且除了开头的记录，后面也没有再报过warning的错误。接着就是开头的报错。虽然是报错，但并未退出安装，packages的列表也还是照常列出，并且看了一下，确实是昨天安装失败的部分（本来应该2g多，昨天安装了一些小的，今天剩下1.96g），数字对的上。
【安装库】WARNING: A newer version of conda exists.
一拳Marx
01-22 3万+
【安装库】WARNING: A newer version of conda exists. conda常见报错以及解决方法【持续更新conda的其它报错以及解决方法。】 大概是出现了如下的报错： 试了好久，直到看到上面这一篇文章，应该是部分库内容有损坏，导致了conda报错，解决方法就是删除并且更新，即可正常使用。 清理损坏包: conda clean --packages --tarballs conda update --all 之后使用正常。 ...
Project-Time-Control-New-Document.rar_软件开发文档_软件项目管理_项目文档
09-24
在"Project Time Control New Document.pdf"中，读者可以期待找到关于这些方面的详细指导、实例和工具，帮助实际操作中的软件项目管理人员提升时间管理能力，实现更有效的项目控制和管理。通过学习和应用这些知识，...
Java-Help-Document.rar_Help!
09-24
10. **工具和框架**：Maven、Gradle用于项目管理和构建，JUnit用于单元测试，Spring框架提供依赖注入和AOP等功能，这些都是Java开发者日常工作中常用的工具和框架。 总的来说，"Java Help Document.chm"可能会涵盖...
行业文档-设计装置-全省水写纸.zip
08-28
"ȫʡˮ"可能是“水写纸”的拼音缩写，"дֽ"可能代表“设计”或“技术”，而".pdf"则是常见的文档格式，表示这是Adobe Portable Document Format，即PDF文件，一种便于分享和打印的文档格式。 基于以上信息，我们...
fcc-technical-document:FreeCodeCamp技术文档项目
03-31
由Matt McCoy于2019年3月12日为FreeCodeCamp的技术文档项目创建的项目 项目目标 响应式Web设计项目-构建技术文档页面目标：构建功能类似于以下代码的CodePen.io应用程序： ://codepen.io/freeCodeCamp/full/NdrKKL...
objective-c pdf document
01-30
PDF文档通常用于分享详尽的技术资料，因此“objective-c pdf document”很可能是一个关于Objective-C编程语言的全面教程或指南。这份文档可能包含了语言的基本概念、语法特性、类库使用以及开发流程等内容。 ...
MonoTorrent.GUI
05-06
基于MonoTorrent组件开发的BT客户端，学习使用MonoTorrent的好资料，不容错过哦（找了好久，分就高了点，：P）
手把手从零搭建一个 vue3 组件库 (二)：为组件编写文档
weixin_43960320的博客
08-23 2158
手把手从零搭建一个 vue3 组件库 (二)：为组件编写文档 本期任务如下： 抽离 eslint-config 定义 css 变量 编写一个 Button 组件 使用 vitepress 为组件编写文
Vue 3.0文档编写指南
2201_75866484的博客
03-26 1818
译者：本章节大部分内容是针对母语是英文的读者，中文用户可略读，除非你想以英文文档编写者的身份参与 Vue docs 的编写，编写文档是一种换位思考的练习。我们并不是在描述客观现实——源代码已经做到了。我们的工作是帮助塑造用户与 Vue 生态系统之间的关系。这份不断发展的指南提供了一些规则和建议，说明如何在 Vue 生态系统中始终如一地做到这一点。
计算机软件开发文档编写指南
mclock的专栏
04-28 4861
一、项目开发计划 1．引言... 11.1编写目的... 11.2项目背景... 11.3定义... 21.4参考资料... 22．项目概述... 22.1工作内容... 22.2条件与限制... 22.3产品... 22.4运行环境... 22.5服务... 32.6验收标准... 33．实施计划... 33.1任务分解... 33.2进度... 33.3预算... 33.4关键问题... 34
如何使用project制定项目计划？（附详细步骤截图）
热门推荐
三石的专栏
07-05 8万+
最近需要使用project制定项目计划，但发现使用过程中各种疑问，网上搜索教程，大部分也都非常零散，各种复制粘贴防不胜防，好气呀   本着知识共享的精神，我整理了下最近一周学到的东西，仅供参考。最近需要使用project制定项目计划，但发现使用过程中各种疑问，网上搜索教程，大部分也都非常零散，各种复制粘贴防不胜防，好气呀   本着知识共享的精神，我整理了下最近一周学到的东西，仅供参考。废话不多说，...
(转)如何有效使用Project-编制进度计划、保存基准
翔飞
07-18 3011
1.前言： 软件产品的研发、升级、定制等，一般都是以项目的形式进行，此时项目进度计划以及资源使用情况就变成了项目经理关注的重点。如何让项目计划有效可控，及时暴露问题？如何查看资源的负荷情况，看资源分配是否合理。 当然，如果你的公司已经实施了专门的PM软件来监督管控，可以忽略本文。否则，你可以用微软的Project来做到这一工作。 我也算是一个专业的从事PM软件产品的人（虽然我们的客户都是...
Project Document
zhouxiangyong88的博客
02-12 409
top document code base code bases data paths
如何写好 README
lzw17750614592的博客
12-19 1327
引言：因为 README，6 个月后的你仍然知道当初写了什么；因为 README，其他人看一眼就能知道是否需要；因为 README，让你的代码更有质量；因为 README，你成了个作家。 README是documentation的一种。 Documentation documentation的潜在用户 包括： 你自己，有可能半年后你看自己的代码，不晓得当时脑子在想啥？ 你同事， 毫无疑问...
怎么写c++ documentation_二年级语文“照样子写句子”习题（附答案）！
weixin_39951419的博客
11-09 299
注：文章结尾有打印方法往期回顾：人教版二年级数学上册一课一练同步练习，可下载完整版！部编版二年级语文上册全250张生字卡片(建议收藏)二年级语文100字暑假日记范文三十篇，给孩子学习！二年级 百字日记+观察作文各20篇，给孩子收藏学习！看图写话学习(写人+写事+写物)200篇(可下载)巧记二年级数学九九乘法口诀表，打好小学计算基础！二年级数学《竖式计算》分类练习，打印给孩子巩固训练！仿写...
ICESat-2 ATLAS大气延迟校正算法理论基础文档
本篇文档是关于ICESat-2项目的ATBD（Algorithm Theoretical Basis Document，算法理论基础文档）的一部分，标题为"ICESat2_ATL03A_ATBD.pdf"。该文档详细介绍了由Goddard Space Flight Center在Maryland的Greenbelt...
评论 1
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值