sphinx生成项目文档

2022-05-11 00:00:00 文档 代码 项目 生成 注释

近在看的是,如何利用sphinx生成文档,以及如何改变主题。

为什么要使用sphinx

首先呢,这里说的sphinx是,一个python可以用来生成项目文档的工具,并不是全文检索sphinx。

从事python开发已有近一年的时间了,自己有做项目的开发,也有项目的维护,直观看来,有一个很大的问题,估计将伴随自己的开发生涯,也将伴随绝大多数python开发人员的开发生涯:

项目注释太少,阅读起来,代码的功能难以明确

比如,维护一个项目时,看到的可能就只是一个项目的名字,然后就是一大堆代码。需要从变量,函数的名字,去猜测功能和意义,以及阅读整个项目的代码,来捋清楚整个逻辑。而开发过程中,往往为了“快速”实现功能,也是不注重注释,甚者,有人的做法是,先实现功能——一堆完全没有代码布局和美感的代码组成。这是很煎熬的事情。

python开发,python本身推荐的便是pythonic,即代码的可阅读性以及可维护性。从代码的布局,抽象,函数,变量的命名可以体现,但,注释也是需要的。

而sphinx便是一个抽取代码项目中的注释,来构成文档的工具,如果项目本身的注释说明是足够的,那么在生成文档后,也非常方便,不需要太多的修改。

那么如果代码注释够多了,需要生成项目文档么?还是有必要的,作为代码的生产者,可能觉得差异不大——反正都要去阅读代码,看注释,何必生成文档。但是,文档生成了,可以让我们更方便的理解项目构成,也能让非代码的生产者,更容易捋清楚项目的构成——我是十分推崇的。

如何使用sphinx生成文档

网上的介绍,实在是太多了,也很实用。大致分3个步骤:

  • 使用pip install sphinx
    安装sphinx工具

  • 使用sphinx-quickstart
    快速的构建一个文档目录,dcos,此处需要注意即将跳出来的选项

  • 使用sphinx-apidoc -o docs\source .
    将项目放进文档目录中

  • 修改文档目录中,config.py
    中的路径,解决找不到项目的问题

  • 使用make html
    生成文档

这里面,将会遇到这么几个坑,也都是有现成的解决方案的:

  • 提示找不到某个模块。
     这需要在config.py
    文件中修改路径

  • 生成的文档样式丑陋
     可以通过在config.py
    中修改sphinx内置的几种主题来实现。这里推荐一个sphinx_rtd_theme
    的主题,使用它,可以生成和tornado的官方文档一样的样式。

效果还是很好的,准备以后自己在构建项目的时候按着这个来。

来源 https://www.modb.pro/db/212319

相关文章