使用mkdocs管理sphinx文档
项目描述
关于
mkinx 允许您将多个 sphinx 文档项目集成到一个主文档列表中，并允许您使用 mkdocs 跨项目文档。
只要 make html 能正常工作，并且构建的代码位于 your_documentation/your_project/build，任何 sphinx 模块都可以使用。
mkinx 附带一个示例项目和独立的文档，您可以立即开始！
默认设置是主文档将使用Material Design主题，项目文档将使用Read The Docs的主题，以更好地区分层次。您可以更改这些设置（在全局 mkdocs.yml 和各个Python项目的 conf.py 中）。
安装
pip install mkinx
入门
使用以下命令开始您的首页文档：
mkinx init your_home_documentation
使用以下命令启动服务器：
mkinx serve
可选地，您可以使用 mkinx serve -s your_port 指定端口号
或手动构建文档：
mkinx build [FLAGS]
标志为：
-v, --verbose verbose flag (Sphinx will stay verbose) -A, --all Build doc for all projects -F, --force force the build, no verification asked -o, --only_index only build projects listed in the Documentation's Home -p, --projects [PROJECTS [PROJECTS ...]] list of projects to build
用法
默认情况下，该软件包附带详细文档，您可以在执行适当的 init 后运行 mkinx serve 来查看。将来可能会有一个托管在Read The Docs上的版本。
内置文档旨在帮助您，但并非必要，您可以覆盖或删除所有内容。 但是，有2个强制性的要求：
1 您必须保持此结构
your_home_documentation/
mkdocs.yml
docs/ # your home documentation, listing sphinx docs
index.md # mandatory file -> mkdocs's index
site/
your_project_1/
build/ # sphinx's build directory
source/ # sphinx's documentation source directory
your_project_1/ # your documented code as a package
__init__.py
your_package_1_1/
your_package_1_2/
...
your_project_2/
build/
source/
your_project_2/
__init__.py
your_package_2_1/
your_package_2_2/
...
...
2 mkdocs 的 index.md 文件必须有一个 # Projects 部分，列出它们，如示例所示
此外，请记住从您的“首页文档”的根目录（例如上面示例中的“your_home_documentation/”）运行 build 或 serve 命令，否则您可能会遇到“mkinx找不到文件”的错误。
添加Python项目
mkinx 附带了一个有用的 autodoc 命令，可以帮助您轻松地将新的Python项目添加到文档中。
您只需将文档（Google风格的docstrings）代码放在 your_home_documentation/ 下的文档中。假设它叫做 your_project_3。然后您只需前往那里并使用 autodoc
$ pwd /path_to_your_documentation/ $ mkdir your_project_3 $ cd your_project_3 $ cp -r path/to/your_project_3 . $ ls your_project_3 $ mkinx autodoc ... some prints $ ls Makefile source build your_project_3
在内部，mkinx autodoc 运行 sphinx-quickstart，更新默认值以兼容 mkinx 设置，运行 sphinx-autoapi，重新排列创建的 .rst 文件，使用 mkinx build 构建文档，并更新首页文档的 index.md 文件以列出 your_project_3。
如果 mkinx autodoc 对 sphinx 文档的默认值不合适，请更新 your_project_3/conf.py。
手动添加构建后的文档
如果您不想使用 mkinx autodoc，您可以使用您想要的任何sphinx配置。只需记住，mkinx 将从您的项目目录运行 make html（因此请检查这可以正常工作），并且 mkinx serve 期望在您的项目目录中的 build/ 目录下找到一个名为 index.html 的文件。
自定义
您可以使用任何其他主题，例如。要使用 mkdocs-nature，只需
pip install mkdocs-nature
然后在 mkdocs.yaml 中更改此设置： theme: nature，最后
mkdocs build
编辑 mkdocs.yaml 中的全局配置以及每个项目的 source/conf.py。
有用的资源
下载文件
下载适合您平台的应用程序。如果您不确定选择哪个，请了解更多关于 安装软件包 的信息。
源分布
构建分布
mkinx-0.3.1.2-py3-none-any.whl 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | bb98db277c3dc8818e8dbf894b334672e9820feb806e59d68f47c5772b6e72a3 |
|
| MD5 | 4890f65e1e756fa14268c8ac6aec00aa |
|
| BLAKE2b-256 | 23251693c7ca9a4a3d5e809ffbc9504d916d80a38420b0080ba8a4c22d2f2acd |