Remove ignore index.rst

.gitignore

@@ -2,7 +2,7 @@
 docfly_venv/
 docfly.egg-info/
 docfly-*/
-index.rst
+
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/source/01-how-to-use/index.rst

@@ -0,0 +1,52 @@
+docfly使用说明
+==============================================================================
+docfly是一个帮助你更容易地使用 `sphinx-doc <http://www.sphinx-doc.org/en/stable/index.html>`_ 来构建你的文档网站的工具。
+
+
+API Reference
+------------------------------------------------------------------------------
+
+如果你在为你的Python代码写文档, Sphinx有一个杀手级的功能: 自动从源代码中摘取docstring, 生成API文档。 然后你就可以使用在你的文档中使用 ``:ref:`modindex``` 引用之。但是, 你需要手动编写大量代码, 告诉Sphinx哪些模块你想要自动为它生成文档。具体做法请参考 `这篇说明 <http://www.sphinx-doc.org/en/stable/ext/autodoc.html>`_。
+
+**docfly** 的 **杀手级功能** 是, 自动分析你的源代码, 然后自动生成 ``:ref:`modindex``` 所需的一切文件。并且在你的源代码结构发生变化之后, 自动更新。下面我们就以docfly本项目本身为例进行说明。你可以在 `这里 <https://github.com/MacHu-GWU/docfly-project>`_ 找到本文档中的示例代码。
+
+1. 在你的项目中创建一个 ``create_doctree.py`` 文件, 将其放在和你文档的source目录的旁边, 也同时是Makefile的旁边(当然你也可以放在任何地方, 不过就需要修改 ``dst`` 参数了), 文件内容如下::
+
+	# Content of create_doctree.py
+
+	import docfly
+
+	#--- Api Reference Doc ---
+	package_name = "docfly"
+
+	doc = docfly.ApiReferenceDoc(
+	    package_name,
+	    dst="source", # your sphinx doc source destination
+	    ignore=[
+	        "%s.pkg" % package_name,
+	        "%s.zzz_ezinstall.py" % package_name,
+	    ]
+	)
+	doc.fly()
+
+2. 如果是Windows, 创建一个 ``build_doc.bat`` 文件(如果是MacOS, Linux系统, 参考Windows命令行创建一个类似的Shell脚本即可), 将其放在 ``create_doctree.py`` 旁边, 内容如下::
+
+	pushd "%~dp0"
+	python create_doctree.py
+	make html
+
+这样你就可以通过双击, 一键Build你自带API文档的网站了。
+
+
+Table of Content
+------------------------------------------------------------------------------
+写一个文档网站就像写一本书。分Chapter, Section, ... 一级一级的往下延伸。而我们希望能自动地从上往下, 为每一章生成它下面每一节的链接, 同理递归下去。
+
+而docfly的另一个重要功能就是: 只要你按照 `Sphinx文档项目规范 <https://github.com/MacHu-GWU/docfly-project/blob/master/source/sphinx-doc-style-guide/content.rst>`_, 那么就可以使用docfly轻松生成章节, 目录的链接, 只要你在 ``create_doctree.py`` 文件中加入以下内容::
+
+	# Uncomment this if you follow Sanhe's Sphinx Doc Style Guide
+	#--- Manually Made Doc ---
+	doc = docfly.DocTree("source")
+	doc.fly()
+
+同理, 你可以使用自动化批处理文件, 一键Build你的文档网站。

docs/source/02-sphinx-doc-style-guide/index.rst

@@ -0,0 +1,41 @@
+.. _Sanhe_sphinx_doc_project_style_guide:
+
+Sanhe's Sphinx文档项目规范
+==============================================================================
+每一个大型项目, 或是某一类的项目通常都有自己的项目规范。这些规范都是从大量的实际项目经验中总结而来。遵循一定的规范可以让你的代码更易读; 而前人的经验往往能帮助你避免很多你所没考虑到的问题。
+
+
+命名空间
+------------------------------------------------------------------------------
+1. 文件名中不要出现空格。
+2. 使用 ``-`` 连接所有的单词, 而不是 ``_``, 这是因为 ``-`` 在Url中是合法字符, 而 ``_`` 不是。
+3. 避免使用形如 ``ThisDocument`` 这样的多个单词不分隔, 而用首字母大写的方式。因为这样命名可读性较差。
+4. 尽量使用全英文数字, 不要使用非英语字符, 但如果你必须要这么做, 也并没有问题
+
+
+.. _page:
+
+页面
+------------------------------------------------------------------------------
+每一个 ``.rst`` 文件在文档网站中代表的是一个页面。笔者推荐, 为你的每一个页面的文档文件, 创建一个独立的目录。其中包含 ``_content.rst``。假设你本来想创建一个文件叫 ``learn-sphinx-doc.rst``, 你应该这样做::
+
+	source
+	|--- learn-sphinx-doc # this is a directory
+	    |--- _content.rst
+	|--- _content.rst # root
+
+而不是::
+
+	source
+	|--- learn-sphinx-doc.rst
+	|--- index.rst # root
+
+这是因为, **你的文件中很可能包含有多个图片, 而你需要在你的文件中引用它们**。为每一个页面创建一个文件夹能够让你每个文件所引用的图片与其他文件的图片分开, 不至于混淆。而你的其他。
+
+``_content.rst`` 文件是你的正文文件, 你需要将你所需要写的所有内容都放在此文件中。而 ``index.rst`` 中的内容则使用 `docfly <https://github.com/MacHu-GWU/docfly-project>`_ 自动生成。**为什么不直接在index.rst中写呢**? 这是因为我们可以通过自动化脚本, 自动根据 ``_content.rst`` 中的文档和新的Markup, 为 ``index.rst`` 生成许多其他内容, 例如 Table of Content。而你可以专注于在 ``_content.rst`` 文件中写内容部分。而其他部分, 可以交给程序自动生成。这样做可以避免错误以及提升工作效率。
+
+
+图片
+------------------------------------------------------------------------------
+如果你使用 `页面 <page_>`_ 一节中的规范, 那么每一个 ``.rst`` 文件中所要引用的图片就应该跟 ``index.rst`` 保持在同一个目录下。如果你没有使用前面所说的规范, 那么建议你创建一个和你的 ``document-title.rst`` 文件同名的文件夹, 并加上 ``images`` 前缀, 例如 ``images-document-title``, 然后将图片放在这一目录内。
+这样可以区分开每个文件所使用的图片。

docs/source/index.rst

@@ -0,0 +1,21 @@
+.. contents::
+
+.. include:: ../../README.rst
+
+Table of Content
+------------------------------------------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+    docfly使用说明 <01-how-to-use/index.rst>
+    Sanhe's Sphinx文档项目规范 <02-sphinx-doc-style-guide/index.rst>
+
+
+.. include:: author.rst
+
+API Document
+------------------------------------------------------------------------------
+
+* :ref:`by Name <genindex>`
+* :ref:`by Structure <modindex>`