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 and PIP. 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 ### How to update dependencies
  24
  25 Once in a while you need to update Python dependencies (for instance,
  26 when Dependabot alerts about possible security flaw). The list of
  27 transitive dependencies (`requirements.txt`) is generated from the
  28 list of direct dependencies in `requirements.in`. To perform the
  29 generation step run
  30
  31 ```console
  32 > make users-guide-requirements
  33 ```
  34
  35 either from the root of the cabal repository or from the `docs/` subdirectory.
  36
  37 Note that generating `requirements.txt` is sensitive to the Python version.
  38 The version currently used is stamped at the top of `requirements.txt`.
  39 Normally, we would expect the same version of Python to be used for
  40 regeneration. An easy way to enforce a particular version is to perform
  41 regeneration in a Docker container, e.g. (from the root of repository):
  42
  43 ```console
  44 > docker run -itv $PWD:/cabal python:3.10-alpine sh
  45 ...
  46 # apk add make
  47 ...
  48 # cd cabal
  49 # make users-guide-requirements
  50 ```
  51
  52 One way to make sure the dependencies are reasonably up to date
  53 is to remove `requirements.txt` and regenerate it as described
  54 above. But in some cases you may have to add a bound manually
  55 to `requirements.in`, e.g. `requests >= 2.31.0`.
  56
  57 ### Gitpod workflow
  58
  59 From a fork of cabal, these docs can be edited online with
  60 [gitpod](https://www.gitpod.io/):
  61
  62 * Open in gitpod https://gitpod.io/#https://github.com/username/cabal
  63 * Install the virtual environment prerequisite.
  64   `> sudo apt install python3.8-venv`
  65 * Build the user guide `> make users-guide`.
  66 * Open the guide in a local browser.
  67   `> python -m http.server 8000 --directory=dist-newstyle/doc/users-guide`
  68
  69 Make your edits, rebuild the guide and refresh the browser to preview the
  70 changes. When happy, commit your changes with git in the included terminal.
  71
  72 ### Caveats, for newcomers to RST from MD
  73 RST does not allow you to skip section levels when nesting, like MD
  74 does.
  75 So, you cannot have
  76
  77 ```
  78     Section heading
  79     ===============
  80
  81     Some unimportant block
  82     """"""""""""""""""""""
  83 ```
  84
  85   instead you need to observe order and either promote your block:
  86
  87 ```
  88     Section heading
  89     ===============
  90
  91     Some not quite so important block
  92     ---------------------------------
  93 ```
  94
  95   or introduce more subsections:
  96
  97 ```
  98     Section heading
  99     ===============
 100
 101     Subsection
 102     ----------
 103
 104     Subsubsection
 105     ^^^^^^^^^^^^^
 106
 107     Some unimportant block
 108     """"""""""""""""""""""
 109 ```
 110
 111 * RST simply parses a file and interprets headings to indicate the
 112   start of a new block,
 113   * at the level implied by the header's *adornment*, if the adornment was
 114   previously encountered in this file,
 115   * at one level deeper than the previous block, otherwise.
 116
 117   This means that a lot of confusion can arise when people use
 118   different adornments to signify the same depth in different files.
 119
 120   To eliminate this confusion, please stick to the adornment order
 121   recommended by the Sphinx team:
 122
 123 ```
 124     ####
 125     Part
 126     ####
 127
 128     *******
 129     Chapter
 130     *******
 131
 132     Section
 133     =======
 134
 135     Subsection
 136     ----------
 137
 138     Subsubsection
 139     ^^^^^^^^^^^^^
 140
 141     Paragraph
 142     """""""""
 143 ```
 144
 145 * The Read-The-Docs stylesheet does not support multiple top-level
 146   sections in a file that is linked to from the top-most TOC (in
 147   `index.rst`). It will mess up the sidebar.
 148   E.g. you cannot link to a `cabal.rst` with sections "Introduction",
 149   "Using Cabal", "Epilogue" from `index.rst`.
 150
 151   One solution is to have a single section, e.g. "All About Cabal", in
 152   `cabal.rst` and make the other blocks subsections of that.
 153
 154   Another solution is to link via an indirection, e.g. create
 155   `all-about-cabal.rst`, where you include `cabal.rst` using  the
 156   `.. toctree::` command and then link to `all-about-cabal.rst` from
 157   `index.rst`.
 158   This will effectively "push down" all blocks by one layer and solve
 159   the problem without having to change `cabal.rst`.
 160
 161
 162 * We use [`extlinks`](http://www.sphinx-doc.org/en/stable/ext/extlinks.html)
 163   to shorten links to commonly referred resources (wiki, issue trackers).
 164
 165   E.g. you can use the more convenient short syntax
 166
 167         :issue:`123`
 168
 169   which is expanded into a hyperlink
 170
 171         `#123 <https://github.com/haskell/cabal/issues/123>`__
 172
 173   See `conf.py` for list of currently defined link shorteners.