网站开发合同属于知识产权类吗,口碑营销5t理论,石家庄网站系统开发,电子商务营销策略论文博主在学习使用 Sphinx 和 Read the docs 的过程中#xff0c; 碰到了许多奇葩的 bug, 使得很简单的任务花费了很长的时间才解决#xff0c;现在在这里做一个分享#xff0c;帮助大家用更少的时间高效上线文档的内容。 总的来说#xff0c; 任务分为两个部分#xff1a;
… 博主在学习使用 Sphinx 和 Read the docs 的过程中 碰到了许多奇葩的 bug, 使得很简单的任务花费了很长的时间才解决现在在这里做一个分享帮助大家用更少的时间高效上线文档的内容。 总的来说 任务分为两个部分
使用 Sphinx 生成文档文档托管到 Read the docs 平台 准备
整个过程基于 python 实现 推荐使用 Anoconda 能够创建管理独立的虚拟环境【 conda使用方法】这样之后在配置文件的时候会方便很多。 使用 Sphinx 生成文档
掌握几个基本语句
安装需要的库: pip install sphinx 快速创建项目sphinx-quickstart独立的源文件和构建目录y/n [n]: 个人填 y接下来所填项目示例 项目名称: Test 作者名称: 摸鱼仙人 项目发行版本 [ ]: v1 项目语种 [en]: zh_CN, 英语则填写 EN
在这之后项目基本创建完成项目框架如图所示 需要关注的主要是 **source** 和 **build** 两个文件夹。
source: 所有的需要的文档都要放在里面 .rst| .md)build所有生成的文件都会保存在里面
⭐ 需要配置**conf.py** 和 **index.rst** 两个文件
---* 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
import sys
import os
# 此处在 sphinx-quickstart 中都进行了填写,一般无需修改
project XXXX
copyright 2024, 摸鱼仙人
author Jin
release v1# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
# 此处为项目文件地址
project_path F:\XXX
sys.path.insert(0, os.path.abspath(../..))# 此处为导入的 md 文件需要的配置
extensions [sphinx_markdown_tables, m2r]
source_suffix [.rst, .md]templates_path [_templates]
exclude_patterns []
# 此处为项目使用语言
language zh_CN# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-outputhtml_theme sphinx_rtd_theme
html_static_path [_static]---* index.rst *---.. XXXXXX documentation master file, created bysphinx-quickstart on Fri Mar 22 07:52:42 2024.You can adapt this file completely to your liking, but it should at leastcontain the root toctree directive.XXXXX
.. toctree:::maxdepth: 3:caption: XXXXch01_数学基础 ch01_数学基础/ch01_数学基础.mdIndices and tables
* :ref:genindex
* :ref:modindex
* :ref:search
需要熟练掌握语法, 由于内容过多, 本处不再赘述.有机会再开一篇详细展开. 配置内容大致相似,修改部分需要的名称即可.
注意:
.. toctree:::maxdepth: 3:caption: XXXX
!-- 此处必须空一行 --ch01_数学基础 ch01_数学基础/ch01_数学基础.md该处的格式掌握两句代码反复使用
make clean: 清除build生成的文件make html: 生成html文件
在 build 文件夹 中, 可以找到 index.html, 可以通过该文件查看生成的结果 没有问题之后, 在 Github 上创建仓库, 将目前文件夹中所有的内容推送上去.
配置 .gitignore 文件
---* .gitignore *---build/托管到 Read the docs 平台
Read the docs 平台: Read the docs
登录平台,使用 Github 账号进行登录 点击 导入一个项目 就可以将 Github 中的项目的文档托管过来, 以后文档的更新只需要在Github 平台上传,此处的托管能够自动的跟进更新
注意: 导入前需要创建 .readthedocs.yaml 文件进行配置, 更新上传在 Github 中
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details# Required
version: 2# Set the OS, Python version and other tools you might need
build:os: ubuntu-22.04tools:python: 3.9# You can also specify other tool versions:# nodejs: 19# rust: 1.64# golang: 1.19# Build documentation in the docs/ directory with Sphinx
sphinx:configuration: source/conf.py# Optionally build your docs in additional formats such as PDF and ePub
# formats:
# - pdf
# - epub# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:install:- requirements: docs/requirements.txt点击导入后有几处地方容易导致报错, 需要注意:
各个模块的内容需要顶格写,否则会出现报错
requirements.txt 文件生成:
在虚拟环境中使用 pip freeze requirements.txt 能够自动生成配置的库的相关参数, 有时候 txt 文本中会出现一些奇怪的内容需要删除: 因此,开始时创建一个干净的虚拟环境十分有利于任务的快速推进.
导入构建后,如果显示如图则生成成功. 如果为红色, 显示 failed 则生成失败. 单击 build 则会在 构建 部分重新运行
通过此处的网址可以直接查看文档的地址: 参考资料
Sphinx Read the Docs 从懵逼到入门使用Read the Docs托管文档Sphinx 学习优质教程
