doc/README.md

   1 Cabal documentation
   2 ===================
   3
   4 ### Where to read it
   5 These docs will be built and deployed whenever a release is made,
   6 and can be read at: https://www.haskell.org/cabal/users-guide/
   7
   8 In addition, the docs are taken directly from git and hosted at:
   9 http://cabal.readthedocs.io/
  10
  11
  12 ### How to build it
  13
  14 Building the documentation requires Python 3, PIP, and `pip-tools` (see the second note below for how to install it). Run the following command either from the root of the cabal repository or from the `docs/` subdirectory:
  15
  16 ``` console
  17 > make users-guide
  18 ```
  19
  20 Note: Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, so unset the variable
  21 and instead set `LC_ALL=en_US.UTF-8`.
  22
  23 Note: You can use a vendor package for `pip-tools`, or run
  24
  25 ``` console
  26 > pip install pip-tools
  27 ```
  28
  29 Make sure the installation directory (often `$HOME/.local/bin`) is on your `$PATH`.
  30
  31 ### How to update dependencies
  32
  33 The list of transitive dependencies (`requirements.txt`) is generated from the list of direct dependencies in `requirements.in`. To perform the generation step, run
  34
  35 ```console
  36 > make users-guide-requirements
  37 ```
  38
  39 either from the root of the cabal repository or from the `docs/` subdirectory. You will need to do this before building documentation the first time, but should only need to repeat it after a `git clean` or if the dependencies in `requirements.in` change.
  40
  41 In some cases, you may have to add a bound manually to `requirements.in`, e.g. `requests >= 2.31.0`.
  42
  43 ### Gitpod workflow
  44
  45 From a fork of cabal, these docs can be edited online with
  46 [gitpod](https://www.gitpod.io/):
  47
  48 * Open in gitpod https://gitpod.io/#https://github.com/username/cabal
  49 * Install the virtual environment prerequisite.
  50   `> sudo apt install python3.8-venv`
  51 * Build the user guide `> make users-guide`.
  52 * Open the guide in a local browser.
  53   `> python -m http.server 8000 --directory=dist-newstyle/doc/users-guide`
  54
  55 Make your edits, rebuild the guide and refresh the browser to preview the
  56 changes. When happy, commit your changes with git in the included terminal.
  57
  58 ### Caveats, for newcomers to RST from MD
  59
  60 RST does not allow you to skip section levels when nesting, like MD
  61 does.
  62 So, you cannot have
  63
  64 ```
  65     Section heading
  66     ===============
  67
  68     Some unimportant block
  69     """"""""""""""""""""""
  70 ```
  71
  72   instead you need to observe order and either promote your block:
  73
  74 ```
  75     Section heading
  76     ===============
  77
  78     Some not quite so important block
  79     ---------------------------------
  80 ```
  81
  82   or introduce more subsections:
  83
  84 ```
  85     Section heading
  86     ===============
  87
  88     Subsection
  89     ----------
  90
  91     Subsubsection
  92     ^^^^^^^^^^^^^
  93
  94     Some unimportant block
  95     """"""""""""""""""""""
  96 ```
  97
  98 * RST simply parses a file and interprets headings to indicate the
  99   start of a new block,
 100   * at the level implied by the header's *adornment*, if the adornment was
 101   previously encountered in this file,
 102   * at one level deeper than the previous block, otherwise.
 103
 104   This means that a lot of confusion can arise when people use
 105   different adornments to signify the same depth in different files.
 106
 107   To eliminate this confusion, please stick to the adornment order
 108   recommended by the Sphinx team:
 109
 110 ```
 111     ####
 112     Part
 113     ####
 114
 115     *******
 116     Chapter
 117     *******
 118
 119     Section
 120     =======
 121
 122     Subsection
 123     ----------
 124
 125     Subsubsection
 126     ^^^^^^^^^^^^^
 127
 128     Paragraph
 129     """""""""
 130 ```
 131
 132 * The Read-The-Docs stylesheet does not support multiple top-level
 133   sections in a file that is linked to from the top-most TOC (in
 134   `index.rst`). It will mess up the sidebar.
 135   E.g. you cannot link to a `cabal.rst` with sections "Introduction",
 136   "Using Cabal", "Epilogue" from `index.rst`.
 137
 138   One solution is to have a single section, e.g. "All About Cabal", in
 139   `cabal.rst` and make the other blocks subsections of that.
 140
 141   Another solution is to link via an indirection, e.g. create
 142   `all-about-cabal.rst`, where you include `cabal.rst` using  the
 143   `.. toctree::` command and then link to `all-about-cabal.rst` from
 144   `index.rst`.
 145   This will effectively "push down" all blocks by one layer and solve
 146   the problem without having to change `cabal.rst`.
 147
 148
 149 * We use [`extlinks`](http://www.sphinx-doc.org/en/stable/ext/extlinks.html)
 150   to shorten links to commonly referred resources (wiki, issue trackers).
 151
 152   E.g. you can use the more convenient short syntax
 153
 154         :issue:`123`
 155
 156   which is expanded into a hyperlink
 157
 158         `#123 <https://github.com/haskell/cabal/issues/123>`__
 159
 160   See `conf.py` for list of currently defined link shorteners.