文档整体解决方案(readthedocs、github 、sphinx)使用

这里是总结了一下，用的工具或者平台：readthedocs、github 、sphinx。 使用这三个工具即可轻松创建高效的文档管理库，可以用来翻译，水平再高一点可以写书。

• readthedocs

文档托管的平台，能够和常用的GIT阵营的github，HG阵营的Bitbucket，关于这两个平台的讨论比较文章可以参考。

• github

代码托管

• sphinx

文档书写利器，使用的是reStructuredText格式，reStructuredText简明教程。

下面说说书写方法及托管流程

1. 在这里注册一个帐号-->登录。
2. git的帐号及使用大家应该很熟悉了，在这里不再赘述。创建一个repo以存放sphinx（我测试用的a-test-sphinx-doc）。

3. 安装sphinx，快速入门

   jwch的成员有人整理这个文档使用shpinx记笔记，按照这个来就可以。

4. 将sphinx生成的文档和配置 push 到git代码仓库[a-test-sphinx-doc]

   evenvi@evenvi-MS-7302:~/mydoc$ git init
   evenvi@evenvi-MS-7302:~/mydoc$ git add .
   evenvi@evenvi-MS-7302:~/mydoc$ git commit -m "test sphinx doc"
   evenvi@evenvi-MS-7302:~/mydoc$ git remote add origin https://github.com/yinlianwei/a-test-sphinx-doc.git
   evenvi@evenvi-MS-7302:~/mydoc$ git push origin master

   经过这些就把你的sphinx生成的文档及一些配置文件等，push到了github

5. 把github中的文档的代码仓库导入到readthedocs

• 首先在github->repo->Admin-ServiceHooks->ReadTheDocs,激活这个选项。
• readthedocs->Import 按照上边的有关字段的提示填写清楚，必要的Name Author Version Repo……,这里注意 conf.py 路径要填写正确（source/conf.py），提交。

这样就文档导入到了readthedocs中，则还是我的测试文档，readthedocs的文档主题简洁，比较不错。当然如果你自己有web服务器，就不用那么麻烦，这里最大好处不用自己维护服务器，可以充分利用github的功能。

sphinx安装使用：

先安装好Python环境，建议选择Pyhon2.7.3,并且把Python及Python/Scripts目录加入环境变量，然后只需要一行命令即可

easy_install -U Sphinx

安装完毕之后，进入任意目录，运行

sphinx-quickstart

会进入一个设置向导，根据向导一步一步设置文档项目，其实必填项只有项目名称，作者和版本，其他设置都可以一路回车：

1. 文档根目录(Root path for the documentation)，默认为当前目录(.)
2. 是否分离文档源代码与生成后的文档(Separate source and build directories): y
3. 模板与静态文件存放目录前缀(Name prefix for templates and static dir):_
4. 项目名称(Project name) : EvaEngine
5. 作者名称(Author name)：AlloVince
6. 项目版本(Project version) : 1.0.1
7. 文档默认扩展名(Source file suffix) : .rst
8. 默认首页文件名(Name of your master document):index
9. 是否添加epub目录(Do you want to use the epub builder):n
10. 启用autodoc|doctest|intersphinx|todo|coverage|pngmath|ifconfig|viewcode：n
11. 生成Makefile (Create Makefile)：y
12. 生成windows用命令行(Create Windows command file):y

最后会生成Sphinx一个文档项目必需的核心文件，包括：

readthedocs
│ make.bat
│ Makefile
├─build
└─source
　　│ conf.py
　　│ index.rst
　　├─_static
　　└─_templates

如果向导中的所有设置都保存在conf.py中，可以随时调整。

Sphinx生成文档

source目录就是存放文档源代码的目录，默认的索引页面为index.rst

我们尝试来写作第一篇文档，在source目录下建立helloworld.rst，内容为：

Hello World ===========

同时编辑index.rst对应部分为

.. toctree::
   :maxdepth: 1

   helloworld

然后在当前目录下运行

make html

会看到build目录下会生成HTML格式的文档。同理我们可以make letex生成LeTex以及其他格式。

参考：

https://read-the-docs.readthedocs.org/en/latest/getting_started.html

http://avnpc.com/pages/writing-best-documentation-by-sphinx-github-readthedocs

如何结合github和sphinx？

主要参考：http://daler.github.io/sphinxdoc-test/includeme.html

Publishing sphinx-generated docs on github

github allows the publishing of static pages associated with a particular repository (called project pages), which you can read more about at http://pages.github.com/,

I frequently use Sphinx (http://sphinx.pocoo.org/) for documenting projects, and would like to have my docs for a repo published to the gh-pages for that repo.

This strategy uses ideas from http://lucasbardella.com/report/hosting-your-sphinx-docs-in-github/, which uses a separate directory for docs and keeps the autogenerated stuff out of the main repo. This in contrast to suggestions on http://pages.github.com/, which does stuff within the repo directory. Using a separate docs dir made things easier for me to figure out and configure easier with the Sphinx makefile.

See http://daler.github.com/sphinxdoc-test for the Sphinx-generated version of this README, created using the commands documented in it...

Protocol

Set up main repository （

main repo建立一个docs文件夹，存放rst源文件）

First set up your main repo. These are the commands I used to set up this very repo (how meta!):

mkdir sphinxdoc-test
cd sphinxdoc-test
git init
touch README
git add README
git commit -m 'first commit'
git remote add origin git@github.com:daler/sphinxdoc-test.git
git push origin master

Throughout this document, I’ll refer to this as the ‘main repo’ or the ‘code dir’.

Set up sphinx within main repository

Make a dir, docs, that will store documentation source from Sphinx:

mkdir sphinxdoc-test/docs

Then set up Sphinx from the docs dir, accepting all the defaults as you see fit:

cd docs
sphinx-quickstart

Set up separate docs repository

（建立一个sphinxdoc-test-docs文件夹（放在分支gh-pages)存放生成的html文件等）。

Now we need to set up a completely new directory that will serve as the build directory for Sphinx. Here I’m calling it sphinxdoc-test-docs. Note that it’s outside of the main repo dir:

cd ..
mkdir sphinxdoc-test-docs
cd sphinxdoc-test-docs

Then clone the repo you just set up on github into a dir called html (which will be created automatically with the following command):

git clone git@github.com:daler/sphinxdoc-test.git html
cd html

The html dir now has a clone of the repo.

Next, create a new branch called gh-pages. This is a special branch name that github looks for in order to build static html pages:

git branch gh-pages

The following commands do git fancy stuff that I don’t completely understand yet, suffice to say that after these 3 commands you switch to the new branch gh-pages and the branch is cleaned out with no files in it:

git symbolic-ref HEAD refs/heads/gh-pages  # auto-switches branches to gh-pages
rm .git/index
git clean -fdx

And confirm we’re on gh-pages:

git branch

I’ll refer to this as the ‘gh-pages repo’.

Makefile changes

OK, now the docs repo is set up. Now it’s time to make some changes to the sphinx-generated Makefile back in the main repo so that it builds documentation in our new gh-pages branch and directory, instead of cluttering the main code dir.

So go back to the code dir’s doc dir:

cd ../sphinxdoc-test
cd docs

Here are the changes we’re going to make to sphinxdoc-test/docs/Makefile . . . first, change:

BUILDDIR      = build

to:

BUILDDIR      = ../../sphinxdoc-test-docs
PDFBUILDDIR   = /tmp
PDF           = ../manual.pdf

The first new line points to the new dir and gh-pages branch we just set up. So now, running make html in sphinxdoc-test/docs will create anhtml dir in ../../sphinxdoc-test-docs . . . and luckily, that’s exactly what we set up the gh-pages repo in.

Before the next two lines make sense, need to make another change . . . I’ve added commented lines pointing to the changes:

latexpdf:
    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    @echo "Running LaTeX files through pdflatex..."
    make -C $(BUILDDIR)/latex all-pdf
    @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

to:

latexpdf:
    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(PDFBUILDDIR)/latex
    #                                          ^^^
    @echo "Running LaTeX files through pdflatex..."
    make -C $(PDFBUILDDIR)/latex all-pdf
    #         ^^^
    cp $(PDFBUILDDIR)/latex/*.pdf $(PDF)
    #^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    @echo "pdflatex finished; see $(PDF)"

All these PDF build dir changes put all the LaTeX stuff in a temporary directory, and then only copy the resulting PDF file to the root dir of the main repo. So no cluttering of the main repo with autogenerated doc files, only the latest build of the PDF manual is included.

index.rst changes

Next, I’d like to only worry about making changes in a single file (README.rst), and have that propagated to all the docs in various places. On github, if you have a README.rst file in the root dir, it’ll be converted to nice-ish looking docs. (Sphinx is much better looking, plus can include module, class, and function documentation to boot, hence going through all this trouble).

So we need to point sphinx’s index.rst to the README.rst file in the root of the main repo. Turns out that relative path names don’t work in index.rst, so here’s a workaround:

Make a new file, sphinxdoc-test/docs/source/includeme.rst. In there, put an include directive pointing to the true``README.rst``. So includeme.rstshould look like this:

.. include:: ../../README.rst

Then in index.rst, add includeme to the toctree. So the relevant part of index.rst should look something like:

.. toctree::
   :maxdepth: 2

   includeme

OK, we should be done with the setup now.

Initial creation and commit workflow

Commit all code and README.rst (and any other doc source files) in the main repo, like always:

git add docs
git add README.rst
git commit -m "added docs and README.rst"

Then, when you’re ready to recreate the docs:

cd docs
make html
make latexpdf

Should probably add the newly built manual:

cd ..
git add manual.pdf
git commit -m "added manual.pdf"

Next, change to the gh-pages repo dir and commit the stuff that the make html command made:

cd ../sphinxdoc-test-docs
git add .
git commit -m "rebuilt docs"

And then publish the newly built docs:

git push origin gh-pages

Rinse and repeat. Of course, you could always add a task to the Makefile to do this building and committing docs, something like:

buildandcommithtml: html latexpdf

    cd $(BUILDDIR)/html; git add . ; git commit -m "rebuilt docs"; git push origin gh-pages

Anyway, now you can view your new pages on http://<user>.github.com/<repo>. So in this case, it’s http://daler.github.com/sphinxdoc-test.

Add a .nojekyll file

The last thing we have to do is add an empty file called .nojekyll in the docs repo. This tells github’s default parsing software to ignore the sphinx-generated pages that are in the gh-pages branch. Make sure you commit it, too:

cd sphinxdoc-test-docs/html (html目录添加nojekyll)
touch .nojekyll
git add .nojekyll
git commit -m "added .nojekyll"

Directory structure

So that we’re on the same page, the final directory structure looks like this:

sphinxdoc-test
|-- pymodule              <-- whatever your normal python package dir structure is
|   |-- somepythonmodule.py
|   `-- othercode.py
|-- docs
|   |-- Makefile          <-- edited as described above
|   `-- source
|       |-- conf.py
|       |-- includeme.rst <-- edited as described above
|       `-- index.rst     <-- edited as described above
|-- manual.pdf            <-- created by running make latexpdf
`-- README.rst            <-- where you do most of your writing

sphinxdoc-test-docs
|-- doctrees              <-- this dir is autogenerated, but not
|   |-- environment.pickle     commited to gh-pages
|   |-- includeme.doctree
|   |-- index.doctree
|   `-- README.doctree
`-- html                  <-- The docs repo, on the gh-pages branch.
    |-- genindex.html          Everything under here is committed.
    |-- includeme.html
    |-- index.html
    |-- objects.inv
    |-- README.html
    |-- search.html
    |-- searchindex.js
    |-- _sources
    |   |-- includeme.txt
    |   |-- index.txt
    |   `-- README.txt
    `-- _static
        |-- basic.css
        |-- default.css
        |-- doctools.js
        |-- file.png
        |-- jquery.js
        |-- minus.png
        |-- plus.png
        |-- pygments.css
        |-- searchtools.js
        |-- sidebar.js
        `-- underscore.js

Setting up cloned repos on another machine

The steps for setting this up on another machine are quite a bit simpler.

The only requirement is that the folder name that will hold the docs repo must have the same relative path name as is referred to in the Makefile. So if on one machine I had these repos in /data/repos/sphinxdoc-test and /data/repos/sphinxdoc-test-docs, I could have them as~/sphinxdoc-test-docs and ~/sphinxdoc-test respectively.

First set up the main repo; in this example I’m putting it right in my home directory. Cloning will automatically create a directory, so you don’t have to make one:

cd ~
git clone git@github.com:daler/sphinxdoc-test.git

OK, that’s done. Now to set up the docs repo. For this, just like for setting it up in the first place, you need to create a dir first (making sure it’s the same name referred to in the edited Makefile) and then change to it and clone the html part of the repo:

cd ~
mkdir sphinxdoc-test-docs
cd sphinxdoc-test-docs
git clone git@github.com:daler/sphinxdoc-test.git html

Now there’s a slight problem – in the newly cloned html dir, there only appears to be one branch and it’s the master branch:

git branch
# * master

The following command will create a local tracking branch to the gh-pages branch:

git checkout -b gh-pages remotes/origin/gh-pages

Now the directories are set up the same way they were in the original setup described above.

General workflow

Now that everything is set up, general workflow is to:

• In the main repo:

  • edit and commit code as usual
  • document stuff in README.rst, commit it as usual
  • document stuff that will be in the documentation, but not on the main page, in other .rst files in thedocs directory.
  • change to docs dir and run make html to generate the html docs in your docs repo. This should not make any changes to the main repo, so you don’t have to commit again
  • if you’re making a PDF manual, make that too with make latexpdf. Depending on where you’re putting the PDF manual, you’ll have to commit and push the new version as well.
  • git push
  • change to the docs repo

• Next, in the docs repo:

  • change to the docs repo (make sure you’re in the html dir)
  • check to make sure you’re on the gh-pages branch
  • git commit -a -m "rebuilt docs"
  • git push origin gh-pages

Done!

另外可参考：http://hi.baidu.com/limodou/item/bffbe725413abd0977272cf6

git遇到的问题：http://www.cnblogs.com/renkangke/archive/2013/05/31/conquerAndroid.html