在linux vps上搭建静态网站程序-sphinx

easy_install sphinx(或pip install sphinx)
mkdir sphinx
cd sphinx
sphinx-quickstart (回答它提出的问题，对于其问题，统统回车，即选择默认值）
显示：
...
Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Creating file ./make.bat.
Finished: An initial directory structure has been created.
...
as3:~/sphinx# ls
_build  conf.py  index.rst  make.bat  Makefile  _static  _templates  test1.rst
as3:~/sphinx# make html  (此命令可在你所选择的输出目录里，生成html文档）
sphinx-build -b html -d _build/doctrees   . _build/html
Making output directory...
Running Sphinx v1.2
loading pickled environment... not yet created
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
writing additional files... (0 module code pages) genindex search
copying static files... done
copying extra files... dumping search index... done
dumping object inventory... done
build succeeded.

Build finished. The HTML pages are in _build/html.
as3:~/sphinx# cd _build/html/
as3:~/sphinx/_build/html# ls
genindex.html  objects.inv  searchindex.js  _static
index.html     search.html  _sources
as3:~/sphinx/_build/html#
可见~/sphinx/_build/html/就是静态网站的根目录。

发贴方法：
 as3:~/sphinx/_build/html# cd ~/sphinx/
  as3:~/sphinx# nano test1.rst
格式为：
测试1
======== （这里“=======”的长度最好是标题长度的2倍）

   这是测试1.（这里空3格，才写正文）
as3:~/sphinx# nano index.rst
 把":maxdepth:"的值由2改为1.然后空一行，写上标题的slug.
.. toctree::
   :maxdepth: 1

   chinese-economy
   fengyuwuzu
   test2
   test1
as3:~/sphinx# make html

演示站点：http://sfx.brite.biz ,
项目地址：http://sphinx-doc.org/
-------------------------------------
 https://github.com/crosspop/okydoky,(To say shortly, it's simply a ReadTheDocs.org for private use.)
-------------------------------------

To generate the documentation, source sphinx environment and do:

make html

You will find the documentation in .build/html/index.html.

To generate twiki pages, use:

make twiki

Where the twikis will be in .build/twiki/.

For more available options, check make help.

from https://github.com/dmwm/tutorials
---------



用Sphinx快速制作文档

简介

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持. 本站当然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx还在继续开发. 下面列出了其良好特性,这些特性在Python官方文档中均有体现:

• 丰富的输出格式: 支持 HTML (包括 Windows 帮助文档), LaTeX (可以打印PDF版本), manual pages（man 文档）, 纯文本
• 完备的交叉引用: 语义化的标签,并可以自动化链接函数,类,引文,术语及相似的片段信息
• 明晰的分层结构: 可以轻松的定义文档树,并自动化链接同级/父级/下级文章
• 美观的自动索引: 可自动生成美观的模块索引
• 精确的语法高亮: 基于 Pygments 自动生成语法高亮
• 开放的扩展: 支持代码块的自动测试,并包含Python模块的自述文档(API docs)等 

Sphinx 使用 reStructuredText 作为标记语言, 可以享有 Docutils 为reStructuredText提供的分析，转换等多种工具.

安装Sphinx

Sphinx为Python语言的一个第三方库。我们需要在终端中输入下列命令进行安装：

1	pip install sphinx

创建Sphinx项目

创建一个用于存放文档的文件夹，然后在该文件夹路径下运行下列命令快速生成Sphinx项目：

1	sphinx-quickstart

接下来会让你选择一些配置：

1. 设置文档的根路径（回车，使用默认设置）

   1 2	Enter the root path for documentation. > Root path for the documentation [.]:

2. 是否分离source和build目录（输入y,选择分离，方便管理）

   1 2 3 4

   You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]:

3. 设定模板前缀（回车，使用默认选项）

   1 2 3 4

   Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. > Name prefix for templates and static dir [_]:

4. 输入项目名称和作者

   1 2 3

   The project name will occur in several places in the built documentation. > Project name: Sphinx-test > Author name(s): test

5. 输入项目版本号

   1 2 3 4 5 6 7

   Sphinx has the notion of a "version" and a "release" for the software. Each version can have multiple releases. For example, for Python the version is something like 2.5 or 3.0, while the release is something like 2.5.1 or 3.0a1. If you don't need this dual structure, just set both to the same value. > Project version []: 1.0.0 > Project release [1.0.0]:

6. 文档语言（回车，默认即可）

   1 2 3 4 5 6 7

   If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see http://sphinx-doc.org/config.html#confval-language. > Project language [en]:

7. 设定文档文就按的后缀

   1 2 3

   The file name suffix for source files. Commonly, this is either ".txt" or ".rst". Only files with this suffix are considered documents. > Source file suffix [.rst]:

8. 设定首页名称（回车，选择默认index即可）

   1 2 3 4 5

   One document is special in that it is considered the top node of the "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. > Name of your master document (without suffix) [index]:

9. 根据需要选择是否开启epub输出(一般用不到，回车默认不开启即可)

   1 2	Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/n) [n]:

10. 根据需求选择是否开启相应的Sphinx拓展功能

    1 2 3 4 5 6 7 8 9 10 11 12 13

    Please indicate if you want to use one of the following Sphinx extensions: > autodoc: automatically insert docstrings from modules (y/n) [n]: y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y > coverage: checks for documentation coverage (y/n) [n]: y > imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y Note: imgmath and mathjax cannot be enabled at the same time. imgmath has been deselected. > ifconfig: conditional inclusion of content based on config values (y/n) [n]: y > viewcode: include links to the source code of documented Python objects (y/n) [n]: y > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: n

11. 创建项目

    1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

    A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: y > Create Windows command file? (y/n) [y]: y Creating file ./conf.py. Creating file ./index.rst,.md. Creating file ./Makefile. Creating file ./make.bat. Finished: An initial directory structure has been created. You should now populate your master file ./index.rst,.md and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

项目创建以后目录结构如下所示:

1 2 3 4 5 6 7 8 9

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

• build:用来存放通过make html生成文档网页文件的目录
• source：存放用于生成文档的源文件
• conf.py: Sphinx的配置文件
• index.rst: 主文档

  定义文档结构

  主文档index.rst的主要功能是被转换成欢迎页, 它包含一个目录表（ “table of contents tree”或者 toctree ). Sphinx 主要功能是使用 reStructuredText, 把许多文件组织成一份结构合理的文档.

toctree指令初始值如下：

1 2	.. toctree:: :maxdepth: 2

你可以在 content 的位置添加文档列表:

1 2 3 4 5

.. toctree:: :maxdepth: 2 tutorial.md ...

注：文档文件放在与index.rst同级目录下。

支持markdown文件、更改文档主题

Spinx本身不支持.md文件生成文档，需要我们使用第三方库recommonmark进行转换。
首先分别运行下列命令安装recommonmark与sphinx_rtd_theme库。

1 2 3

pip install recommonmark pip install sphinx_rtd_theme

安装好，在conf.py中修改下列两个配置：

1 2	source_suffix = ['.rst', '.md', '.MD'] html_theme = 'sphinx_rtd_theme'

并新增：

1 2 3 4

source_parsers = { '.md': CommonMarkParser, '.MD': CommonMarkParser, }

生成文档

在Sphinx项目所在的文件夹路径下运行下列命令生成文档：

1

make html

生成后的文档位于build/html文件夹内，用浏览器打开index.html即可看到生成后的文档。

---

参考文章

1. Sphinx 使用手册
2. 使用 sphinx 制作简洁而又美观的文档

------------------

Create a personal website with Sphinx

Sphinx is a documentation generator which converts reStructuredText files into HTML websites and other formats e.g. LaTeX (PDF) and man pages. It’s also a good idea to create simple static website with Sphinx, for example, a personal profile site.

However, as the default purpose of Sphinx is to create documentation, it requires some customization regarding template structure and style. The following steps help create a simple profile site based on the built-in themes of Sphinx.

1. Download Sphinx, create a base directory and quick-start Sphinx. It’ll be helpful to answer “yes” to “Create Makefile?” during sphinx-quickstart:

   $ easy_install -U sphinx
   $ mkdir base_dir
   $ cd base_dir
   $ sphinx-quickstart
   

2. Change site title.
   Edit conf.py in the source directory and make the following modifications:

   html_title = "YOUR SITE TITLE"
   #version = '0.0.1'
   #release = '0.0.1'
   

   Comment version and release to prevent this version number from being displayed in titles.
3. Customize the content structure based on “basic” theme or its derivatives (“default” and “nature”). We take “nature” as an example here.
   First, edit conf.py and make the following modifications:

   html_theme = 'nature'
   html_sidebars = {'**':['localtoc.html','searchbox.html']}
   

   html_sidebars determines the built-in templates to be displayed in the sidebar. For other built-in templates and detailed information, see html_sidebars.
   Second, make sure the settings of the following variables:

   templates_path = ['_templates']
   html_static_path = ['_static']
   

   _templates directory stores template files; _static directory stores static files such as CSS and images. These two directories reside in source directory.
   Third, create your own template layout.html inheriting from the default theme:

   $ cd source/_template
   $ vi layout.html
   

   Edit layout.html:

   {% extends "!layout.html" %}
   {%- set rellinks = [] %}
   {% block rootrellink %}</pre>
   <ul>
       <li><a href="index.html">Home</a> |</li>
       <li><a href="resume.html">Resume</a> |</li>
       <li><a href="projects.html">Projects</a> |</li>
       <li><a href="interest.html">Interest</a> |</li>
       <li><a href="contact.html">Contact</a></li>
       <li>{% endblock %}
   {% block relbar2 %}
   {% endblock %}
   The template above creates a header navigation bar of different entries of your sites.
   
   {%- set rellinks = [] %} disables related links (i.e. prev, next and index).
   

4. Create reStructuredText (.rst) source files for your entries (index.html, resume.html, projects.html, interest.html, contact.html):

   $ cd source
   $ vi index.rst
   

   Use the following format, which also applies to other .rst files, such as resume.rst, projects.rst, interest.html and contact.html.

   Welcome
   *******
   Welcome to my site!
   
   About me
   ========
   I am Blah Blah ...
   
   More info
   =========
   Blah...
   
   .. toctree::
      :maxdepth: 2
   

5. Add a logo for your site.
   First, copy your logo image to the source/_static directory.
   Then, edit conf.py:

   html_logo = "logo.jpg"
   

6. Modify style sheets.
   First, edit conf.py and specify your CSS file name:

   html_style = "mystyle.css"
   

   Second, create your CSS file the source/_static directory:

   $ cd source/_static
   $ vi mystyle.css
   

   Then, edit your CSS file by inheriting default theme CSS, nature.css in our example.

   @import url("nature.css");
   
   body {
     font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
     font-size: 14px;
     font-weight: 300;
     background-color:#333;
   
   }
   
   div.sphinxsidebar {
     font-size: 0.9em;
     line-height: 1.5em;
   }
   
   div.sphinxsidebarwrapper{
     margin-left:10px;
     padding: 5px 0 10px 0;
   }
   
   div.related {
     background-color:#5F95CE;
     font-size: 1em;
   }
   

7. Build your source files from base_dir.

   $ make html
   $ sphinx-build -b html -d build/doctrees source build/html
   

   Use the following commands if your modification to CSS files does not take effect

   $ sphinx-build -a -b html -d build/doctrees source build/html
   

8. Finish. HTML files are generated in build/html, and your site is ready to be visited.