.. highlight:: rst ============================ reStructuredText with Sphinx ============================ ----------------- Setting up Sphinx ----------------- ^^^^^^^^^^ Windows XP ^^^^^^^^^^ * 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. ^^^^^^^^^ Windows 7 ^^^^^^^^^ * 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. ^^^^^^^^^^^^^^^ Debianoid Linux ^^^^^^^^^^^^^^^ * 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 -------------------------- Creating the documentation -------------------------- * 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.py`` Documentation configuration file. ``index.rst`` Documentation master file. ``Makefile`` Make file to generate documentation on Linux/Unix. ``make.bat`` Batch 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 ``tutorial`` refers to a document called ``tutorial.rst`` in 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 (add ``example`` to ``toctree`` in ``index.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-C`` and ``Ctrl-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 `_ * 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.png`` * Bullet 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 comment * Citations (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 html Linux:: 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:: .\make Linux:: make Among others, there should be HTML, LaTeX, Windows HTML Help (chm), man, and so on. The generated documentation will be found in the ``_build`` directory, each format in its own subdirectory (e.g. ``_build/html`` for HTML). ------------------------------------------------------------- Some extra features interesting for programming documentation ------------------------------------------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^ Source code highlighting ^^^^^^^^^^^^^^^^^^^^^^^^ 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); } ^^^^^^^^^^^^^^^^ Cross-file links ^^^^^^^^^^^^^^^^ 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. --------------------- Example documentation --------------------- * `Python documentation `_ * `Zope documentation `_ * `D:YAML documentation `_ ----- Links ----- * `Sphinx `_ * `Sphinx tutorial `_ * `reStructuredText Primer `_ * `Quick reStructuredText reference `_ * `Sphinx documentation `_ * `rst2pdf (generates PDF from reStructuredText) `_