sphinx生成项目文档

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

为什么要使用sphinx

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

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

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

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

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

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

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

如何使用sphinx生成文档

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

使用 安装sphinx工具

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

使用将项目放进文档目录中

修改文档目录中，中的路径，解决找不到项目的问题

使用生成文档

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

提示找不到某个模块。

这需要在文件中修改路径

生成的文档样式丑陋

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

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