Install Python 2.7
Install Python Setuptools (a package manager)
Set PATH environment variable for Python scripts:
Right-click My Computer
Click Properties
Go to the Advanced tab
Click the Environment Variables button
From System Variables, select Path, and click Edit
Assuming you installed Python to
C:\Python27(the default), add this to the end of Variable value:;C:\Python27;C:\Python27\Scripts
Launch the terminal: Click Start, then Run, write
cmd, press Enter.Install Sphinx by typing the following commands to the terminal:
easy_install pip pip install sphinx
Do not close the terminal, you are going to need it.
Install Python 2.7
Install Python Setuptools (a package manager)
Set PATH environment variable for Python scripts:
Right-click Computer
Click Properties
Go to the Advanced system settings tab
Click the Environment Variables button
From System Variables, select Path, and click Edit
Assuming you installed Python to
C:\Python27(the default), add this to the end of Variable value:;C:\Python27;C:\Python27\Scripts
Launch the terminal: Click Start, find Powershell, click it.
Install Sphinx by typing the following commands to the terminal. There might be some errors, those should not be a problem (probably):
easy_install pip pip install sphinx
Do not close the terminal, you are going to need it.
Python is installed (Unless you're using a brutally lightweight distro. Probably not ideal for documentation production).
Install Sphinx by typing the following commands to the terminal:
sudo apt-get install python-pip sudo pip install sphinx
Now, still in the terminal, create a directory for your documentation and move there.
Windows XP:
md mydoc cd mydoc
Win7/Linux:
mkdir mydoc cd mydoc
And finally generate a basic documentation template:
sphinx-quickstart
Quickstart will ask you some questions. The only questions that should interest you for now are:
- Project name:
- Author name:
- Project version
You can skip the others by pressing Enter. This will set up default settings.
You can change any of these options later (you will be changing at least the version as your project develops).
This created a documentation source directory. Important files in this directory:
Directory
Contents
conf.pyDocumentation configuration file.
index.rstDocumentation master file.
MakefileMake file to generate documentation on Linux/Unix.
make.batBatch file to generate documentation on Windows.
The master document,
index.rst, serves as a table of contents and welcome page for the documentation.It contains a heading, table of contents, and a section called Indices and Tables with references for module index, search and so on.
You probably won't need the Indices and Tables section for now, so I recommend to remove it. (This section is added with Python documentation in mind - getting module index and search to work for non-Python documentation would need some googling.)
reStructuredText depends on indentation. For example, below, each entry in the table of contents has the same indentation. This is always 3 spaces, no tabs. Less or more might work, or it might not.
By default, the table of contents should look like this:
Contents: .. toctree:: :maxdepth: 2
You can add documents to the table of contents like this:
Contents: .. toctree:: :maxdepth: 2 tutorial
tutorialrefers to a document calledtutorial.rstin the documentation directory.Example table of contents from a real project:
Tutorials: .. toctree:: :maxdepth: 2 tutorials/getting_started tutorials/custom_types tutorials/yaml_syntax Articles: .. toctree:: :maxdepth: 2 articles/spec_differences
Here we see documents in subdirectories of the documentation directory.
Now create some content.
Create a new reStructuredText file, for example
example.rst, in the documentation directory. Add it to table of contents (addexampletotoctreeinindex.rst.)Open the file in any text editor (MS Word is not a text editor). When saving the file, make sure to use the UTF-8 encoding.
Use source code of this tutorial as a reference.
Use
Ctrl-CandCtrl-V. Do random stuff to try what does what.For example you can do this:
Text:
An extremely awesome sentence. Another mega-awesome sentence. Lines that are together form a paragraph. Lines that are apart form separate paragraphs.
emphasized text :
*emphasized text*strong text :
**strong text**literal text``literal text``A link :
`A link <http://www.google.com>`_
A code block (note the empty line and 3 spaces of indentation):
A code block:: print "Hello World!"Headings:
Level 1 ======= =================================================== This is level 1 too, but looks better in plain text =================================================== Level 2 ------- Level 3 ^^^^^^^ Level 4 """""""
An image:
.. image:: image.pngBullet lists:
* this is * a list * with a nested list * and some subitems * and here the parent list continues
Numbered lists:
1. This is a numbered list. 2. It has two items too.
Can be automatically numbered:
#. This is a numbered list. #. It has two items too.
Tables:
====== ============ ======= No. Availability Name ====== ============ ======= 1 N/A Biros 2 42 piskoty 3 N/A beton ====== ============ =======
Comments:
.. my awesome commentCitations (the citation itself must be at the end of file):
Here is a citation reference: [CIT2002]_. .. [CIT2002] This is the citation.
For more stuff, see the reStructuredText Primer .
Now generate the documentation.
WinXP/Win7:
.\make htmlLinux:
make html
This will generate the documentation in HTML format. To find out what other formats are available, use make with no arguments:
WinXP/Win7:
.\makeLinux:
make
Among others, there should be HTML, LaTeX, Windows HTML Help (chm), man, and so on.
The generated documentation will be found in the
_builddirectory, each format in its own subdirectory (e.g._build/htmlfor HTML).
The code-block directive can be used to highlight source code.
Just about any language is supported. E.g. c for C, cpp for C++,
java for Java, also python, ruby, yaml, xml, etc, etc...
Example highighing D source code where we also use :linenos: to
get line numbers and :emphasize-lines: to emphasize lines 1, 2 and 4:
.. code-block:: d
:linenos:
:emphasize-lines: 1,2,4
import std.stdio;
import yaml;
void main()
{
//Read the input.
Node root = Loader("input.yaml").load();
//Display the data read.
foreach(string word; root["Hello World"])
{
writeln(word);
}
writeln("The answer is ", root["Answer"].as!int);
//Dump the loaded document to output.yaml.
Dumper("output.yaml").dump(root);
}Sections can be labelled by labels in format .. _LABELNAME:,
where LABELNAME is the name of your label (duh).
They can be referenced like this: :ref:`LABELNAME` .
Example:
.. _the-awesome-section:
This Section is Awesome
-----------------------
This text is awesomely recursive: :ref:`the-awesome-section`This works even across different files.
This is better than plain links because it works even if files get renamed.