└── README.rst /README.rst: -------------------------------------------------------------------------------- 1 | .. highlight:: rst 2 | 3 | ============================ 4 | reStructuredText with Sphinx 5 | ============================ 6 | 7 | ----------------- 8 | Setting up Sphinx 9 | ----------------- 10 | 11 | ^^^^^^^^^^ 12 | Windows XP 13 | ^^^^^^^^^^ 14 | 15 | * Install `Python 2.7 `_ 16 | * Install `Python Setuptools `_ (a package manager) 17 | * Set PATH environment variable for Python scripts: 18 | 19 | - Right-click *My Computer* 20 | - Click *Properties* 21 | - Go to the *Advanced* tab 22 | - Click the *Environment Variables* button 23 | - From *System Variables*, select *Path*, and click *Edit* 24 | - Assuming you installed Python to ``C:\Python27`` (the default), add this to the end of *Variable value*:: 25 | 26 | ;C:\Python27;C:\Python27\Scripts 27 | 28 | * Launch the terminal: Click *Start*, then *Run*, write ``cmd``, press Enter. 29 | * Install Sphinx by typing the following commands to the terminal:: 30 | 31 | easy_install pip 32 | pip install sphinx 33 | 34 | * Do not close the terminal, you are going to need it. 35 | 36 | ^^^^^^^^^ 37 | Windows 7 38 | ^^^^^^^^^ 39 | 40 | * Install `Python 2.7 `_ 41 | * Install `Python Setuptools `_ (a package manager) 42 | * Set PATH environment variable for Python scripts: 43 | 44 | - Right-click *Computer* 45 | - Click *Properties* 46 | - Go to the *Advanced system settings* tab 47 | - Click the *Environment Variables* button 48 | - From *System Variables*, select *Path*, and click *Edit* 49 | - Assuming you installed Python to ``C:\Python27`` (the default), add this to the end of *Variable value*:: 50 | 51 | ;C:\Python27;C:\Python27\Scripts 52 | 53 | * Launch the terminal: Click *Start*, find *Powershell*, click it. 54 | * Install Sphinx by typing the following commands to the terminal. There might be some errors, those should not be a problem (probably):: 55 | 56 | easy_install pip 57 | pip install sphinx 58 | 59 | * Do not close the terminal, you are going to need it. 60 | 61 | ^^^^^^^^^^^^^^^ 62 | Debianoid Linux 63 | ^^^^^^^^^^^^^^^ 64 | 65 | * Python is installed (Unless you're using a brutally lightweight distro. Probably not ideal for documentation production). 66 | * Install Sphinx by typing the following commands to the terminal:: 67 | 68 | sudo apt-get install python-pip 69 | sudo pip install sphinx 70 | 71 | 72 | -------------------------- 73 | Creating the documentation 74 | -------------------------- 75 | 76 | * Now, still in the terminal, create a directory for your documentation and move there. 77 | 78 | Windows XP:: 79 | 80 | md mydoc 81 | cd mydoc 82 | 83 | Win7/Linux:: 84 | 85 | mkdir mydoc 86 | cd mydoc 87 | 88 | * And finally generate a basic documentation template:: 89 | 90 | sphinx-quickstart 91 | 92 | * Quickstart will ask you some questions. 93 | The only questions that should interest you for now are: 94 | 95 | - *Project name:* 96 | - *Author name:* 97 | - *Project version* 98 | 99 | You can skip the others by pressing Enter. 100 | This will set up default settings. 101 | 102 | You can change any of these options later (you will be changing at least the version as your project develops). 103 | 104 | * This created a documentation source directory. 105 | Important files in this directory: 106 | 107 | =============== ======================================================================= 108 | Directory Contents 109 | =============== ======================================================================= 110 | ``conf.py`` Documentation configuration file. 111 | ``index.rst`` Documentation master file. 112 | ``Makefile`` Make file to generate documentation on Linux/Unix. 113 | ``make.bat`` Batch file to generate documentation on Windows. 114 | =============== ======================================================================= 115 | 116 | * The master document, ``index.rst``, serves as a table of contents and 117 | welcome page for the documentation. 118 | 119 | It contains a heading, table of contents, and a section called 120 | *Indices and Tables* with references for module index, search and so on. 121 | 122 | You probably won't need the *Indices and Tables* section for now, so I 123 | recommend to remove it. (This section is added with Python documentation 124 | in mind - getting module index and search to work for non-Python documentation 125 | would need some googling.) 126 | 127 | 128 | reStructuredText depends on indentation. For example, 129 | below, each entry in the table of contents has the same indentation. 130 | This is always **3 spaces**, no tabs. Less or more might work, or it might not. 131 | 132 | By default, the table of contents should look like this:: 133 | 134 | Contents: 135 | 136 | .. toctree:: 137 | :maxdepth: 2 138 | 139 | You can add documents to the table of contents like this:: 140 | 141 | Contents: 142 | 143 | .. toctree:: 144 | :maxdepth: 2 145 | 146 | tutorial 147 | 148 | ``tutorial`` refers to a document called ``tutorial.rst`` in the documentation directory. 149 | 150 | Example table of contents from a real project:: 151 | 152 | Tutorials: 153 | 154 | .. toctree:: 155 | :maxdepth: 2 156 | 157 | tutorials/getting_started 158 | tutorials/custom_types 159 | tutorials/yaml_syntax 160 | 161 | Articles: 162 | 163 | .. toctree:: 164 | :maxdepth: 2 165 | 166 | articles/spec_differences 167 | 168 | Here we see documents in subdirectories of the documentation directory. 169 | 170 | 171 | * Now create some content. 172 | 173 | Create a new reStructuredText file, for example ``example.rst``, in the documentation directory. 174 | Add it to table of contents (add ``example`` to ``toctree`` in ``index.rst``.) 175 | 176 | Open the file in any text editor (MS Word is not a text editor). 177 | When saving the file, **make sure** to use the UTF-8 encoding. 178 | 179 | Use `source code of this tutorial `_ 180 | as a reference. 181 | 182 | Use ``Ctrl-C`` and ``Ctrl-V`` . Do random stuff to try what does what. 183 | 184 | 185 | For example you can do this: 186 | 187 | * Text:: 188 | 189 | An extremely awesome sentence. Another mega-awesome sentence. 190 | Lines that are together form a paragraph. 191 | 192 | Lines that are apart form separate paragraphs. 193 | 194 | * *emphasized text* : ``*emphasized text*`` 195 | * **strong text** : ``**strong text**`` 196 | * ``literal text`` :: 197 | 198 | ``literal text`` 199 | 200 | * `A link `_ : :: 201 | 202 | `A link `_ 203 | 204 | * A code block (note the empty line and **3 spaces** of indentation):: 205 | 206 | A code block:: 207 | 208 | print "Hello World!" 209 | 210 | * Headings:: 211 | 212 | Level 1 213 | ======= 214 | 215 | =================================================== 216 | This is level 1 too, but looks better in plain text 217 | =================================================== 218 | 219 | Level 2 220 | ------- 221 | 222 | Level 3 223 | ^^^^^^^ 224 | 225 | Level 4 226 | """"""" 227 | 228 | * An image: ``.. image:: image.png`` 229 | 230 | * Bullet lists:: 231 | 232 | * this is 233 | * a list 234 | 235 | * with a nested list 236 | * and some subitems 237 | 238 | * and here the parent list continues 239 | 240 | * Numbered lists:: 241 | 242 | 1. This is a numbered list. 243 | 2. It has two items too. 244 | 245 | * Can be automatically numbered:: 246 | 247 | #. This is a numbered list. 248 | #. It has two items too. 249 | 250 | * Tables:: 251 | 252 | ====== ============ ======= 253 | No. Availability Name 254 | ====== ============ ======= 255 | 1 N/A Biros 256 | 2 42 piskoty 257 | 3 N/A beton 258 | ====== ============ ======= 259 | 260 | * Comments:: 261 | 262 | .. my awesome comment 263 | 264 | * Citations (the citation itself must be at the end of file):: 265 | 266 | Here is a citation reference: [CIT2002]_. 267 | 268 | .. [CIT2002] This is the citation. 269 | 270 | For more stuff, see the `reStructuredText Primer `_ . 271 | 272 | 273 | * Now generate the documentation. 274 | 275 | WinXP/Win7:: 276 | 277 | .\make html 278 | 279 | Linux:: 280 | 281 | make html 282 | 283 | This will generate the documentation in HTML format. To find out what other formats 284 | are available, use make with no arguments: 285 | 286 | WinXP/Win7:: 287 | 288 | .\make 289 | 290 | Linux:: 291 | 292 | make 293 | 294 | Among others, there should be HTML, LaTeX, Windows HTML Help (chm), man, and so on. 295 | 296 | The generated documentation will be found in the ``_build`` directory, each format 297 | in its own subdirectory (e.g. ``_build/html`` for HTML). 298 | 299 | 300 | ------------------------------------------------------------- 301 | Some extra features interesting for programming documentation 302 | ------------------------------------------------------------- 303 | 304 | ^^^^^^^^^^^^^^^^^^^^^^^^ 305 | Source code highlighting 306 | ^^^^^^^^^^^^^^^^^^^^^^^^ 307 | 308 | The ``code-block`` directive can be used to highlight source code. 309 | Just about any language is supported. E.g. ``c`` for C, ``cpp`` for C++, 310 | ``java`` for Java, also ``python``, ``ruby``, ``yaml``, ``xml``, etc, etc... 311 | 312 | Example highighing D source code where we also use ``:linenos:`` to 313 | get line numbers and ``:emphasize-lines:`` to emphasize lines 1, 2 and 4:: 314 | 315 | .. code-block:: d 316 | :linenos: 317 | :emphasize-lines: 1,2,4 318 | 319 | import std.stdio; 320 | import yaml; 321 | 322 | void main() 323 | { 324 | //Read the input. 325 | Node root = Loader("input.yaml").load(); 326 | 327 | //Display the data read. 328 | foreach(string word; root["Hello World"]) 329 | { 330 | writeln(word); 331 | } 332 | writeln("The answer is ", root["Answer"].as!int); 333 | 334 | //Dump the loaded document to output.yaml. 335 | Dumper("output.yaml").dump(root); 336 | } 337 | 338 | ^^^^^^^^^^^^^^^^ 339 | Cross-file links 340 | ^^^^^^^^^^^^^^^^ 341 | 342 | Sections can be labelled by labels in format ``.. _LABELNAME:``, 343 | where LABELNAME is the name of your label (duh). 344 | 345 | They can be referenced like this: ``:ref:`LABELNAME``` . 346 | 347 | Example:: 348 | 349 | .. _the-awesome-section: 350 | 351 | This Section is Awesome 352 | ----------------------- 353 | 354 | This text is awesomely recursive: :ref:`the-awesome-section` 355 | 356 | 357 | This works even across different files. 358 | 359 | This is better than plain links because it works even if files get renamed. 360 | 361 | 362 | --------------------- 363 | Example documentation 364 | --------------------- 365 | 366 | * `Python documentation `_ 367 | * `Zope documentation `_ 368 | * `D:YAML documentation `_ 369 | 370 | ----- 371 | Links 372 | ----- 373 | 374 | * `Sphinx `_ 375 | * `Sphinx tutorial `_ 376 | * `reStructuredText Primer `_ 377 | * `Quick reStructuredText reference `_ 378 | * `Sphinx documentation `_ 379 | * `rst2pdf (generates PDF from reStructuredText) `_ 380 | 381 | --------------------------------------------------------------------------------