| 1 | .. _building_documentation: |
|---|
| 2 | |
|---|
| 3 | Building Documentation (Linux OS only) |
|---|
| 4 | ************************************** |
|---|
| 5 | |
|---|
| 6 | We use the excellent `Sphinx <http://sphinx.pocoo.org/>`_ Python |
|---|
| 7 | documentation generator to generate the docs as HTML pages. |
|---|
| 8 | |
|---|
| 9 | Prerequisites |
|---|
| 10 | ============= |
|---|
| 11 | |
|---|
| 12 | We assume you already installed `waeup.kofa` as explained in |
|---|
| 13 | :ref:`installing_linux`. You ran ``bin/buildout`` and can find a script |
|---|
| 14 | ``bin/waeupdocs``. |
|---|
| 15 | |
|---|
| 16 | Building HTML docs |
|---|
| 17 | ================== |
|---|
| 18 | |
|---|
| 19 | The documentation of the :mod:`waeup.kofa` project can easily be |
|---|
| 20 | created doing:: |
|---|
| 21 | |
|---|
| 22 | $ bin/waeupdocs |
|---|
| 23 | |
|---|
| 24 | This will create a tree of HTML pages in |
|---|
| 25 | ``docs/build/html`` which you can for |
|---|
| 26 | instance browse by pointing your browser to this location. |
|---|
| 27 | |
|---|
| 28 | An 'official' place in internet for the whole docs is about to come |
|---|
| 29 | but not yet available. |
|---|
| 30 | |
|---|
| 31 | Actually, ``waeupdocs`` is only a wrapper script around the real main |
|---|
| 32 | script ``sphinx-build``, which should also be located in your ``bin/`` |
|---|
| 33 | directory. |
|---|
| 34 | |
|---|
| 35 | You therefore can also run ``bin/sphinx-build`` manually, which will |
|---|
| 36 | give you more options, especially, if you want the output to be |
|---|
| 37 | created in a different location or similar. |
|---|
| 38 | |
|---|
| 39 | Run:: |
|---|
| 40 | |
|---|
| 41 | $ bin/sphinx-build --help |
|---|
| 42 | |
|---|
| 43 | to get a list of options available. |
|---|
| 44 | |
|---|
| 45 | Alternatively, you can also go to ``docs/build`` and run:: |
|---|
| 46 | |
|---|
| 47 | $ make html |
|---|
| 48 | |
|---|
| 49 | Other available formats are listed, when you run only:: |
|---|
| 50 | |
|---|
| 51 | $ make |
|---|
| 52 | |
|---|
| 53 | These other formats will include ``latex``, ``doctest``, ``linkcheck`` |
|---|
| 54 | and more with a short explanation for each format. |
|---|
| 55 | |
|---|
| 56 | Building PDF docs |
|---|
| 57 | ================= |
|---|
| 58 | |
|---|
| 59 | We're currently not prepared for PDF, but support is already planned. |
|---|
| 60 | |
|---|
| 61 | Please be aware, that any PDF support will require a full TeX |
|---|
| 62 | installation on your system to work. |
|---|
