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 be installed
  15 * `> make users-guide`
  16 * Python on Mac OS X dislikes `LC_CTYPE=UTF-8`, unset the env var in
  17 terminal preferences and instead set `LC_ALL=en_US.UTF-8` or something
  18
  19 ### Gitpod workflow
  20
  21 From a fork of cabal, these docs can be edited online with
  22 [gitpod](https://www.gitpod.io/):
  23
  24 * Open in gitpod https://gitpod.io/#https://github.com/username/cabal
  25 * Install the virtual environment prerequisite.
  26   `> sudo apt install python3.8-venv`
  27 * Build the user guide `> make users-guide`.
  28 * Open the guide in a local browser.
  29   `> python -m http.server 8000 --directory=dist-newstyle/doc/users-guide`
  30
  31 Make your edits, rebuild the guide and refresh the browser to preview the
  32 changes. When happy, commit your changes with git in the included terminal.
  33
  34 ### Caveats, for newcomers to RST from MD
  35 RST does not allow you to skip section levels when nesting, like MD
  36 does.
  37 So, you cannot have
  38
  39 ```
  40         Section heading
  41         ===============
  42
  43         Some unimportant block
  44         """"""""""""""""""""""
  45 ```
  46
  47   instead you need to observe order and either promote your block:
  48
  49 ```
  50     Section heading
  51     ===============
  52
  53     Some not quite so important block
  54     ---------------------------------
  55 ```
  56
  57   or introduce more subsections:
  58
  59 ```
  60     Section heading
  61     ===============
  62
  63     Subsection
  64     ----------
  65
  66     Subsubsection
  67     ^^^^^^^^^^^^^
  68
  69     Some unimportant block
  70     """"""""""""""""""""""
  71 ```
  72
  73 * RST simply parses a file and interprets headings to indicate the
  74   start of a new block,
  75   * at the level implied by the header's *adornment*, if the adornment was
  76   previously encountered in this file,
  77   * at one level deeper than the previous block, otherwise.
  78
  79   This means that a lot of confusion can arise when people use
  80   different adornments to signify the same depth in different files.
  81
  82   To eliminate this confusion, please stick to the adornment order
  83   recommended by the Sphinx team:
  84
  85 ```
  86     ####
  87     Part
  88     ####
  89
  90     *******
  91     Chapter
  92     *******
  93
  94     Section
  95     =======
  96
  97     Subsection
  98     ----------
  99
 100     Subsubsection
 101     ^^^^^^^^^^^^^
 102
 103     Paragraph
 104     """""""""
 105 ```
 106
 107 * The Read-The-Docs stylesheet does not support multiple top-level
 108   sections in a file that is linked to from the top-most TOC (in
 109   `index.rst`). It will mess up the sidebar.
 110   E.g. you cannot link to a `cabal.rst` with sections "Introduction",
 111   "Using Cabal", "Epilogue" from `index.rst`.
 112
 113   One solution is to have a single section, e.g. "All About Cabal", in
 114   `cabal.rst` and make the other blocks subsections of that.
 115
 116   Another solution is to link via an indirection, e.g. create
 117   `all-about-cabal.rst`, where you include `cabal.rst` using  the
 118   `.. toctree::` command and then link to `all-about-cabal.rst` from
 119   `index.rst`.
 120   This will effectively "push down" all blocks by one layer and solve
 121   the problem without having to change `cabal.rst`.
 122
 123
 124 * We use [`extlinks`](http://www.sphinx-doc.org/en/stable/ext/extlinks.html)
 125   to shorten links to commonly referred resources (wiki, issue trackers).
 126
 127   E.g. you can use the more convenient short syntax
 128
 129         :issue:`123`
 130
 131   which is expanded into a hyperlink
 132
 133         `#123 <https://github.com/haskell/cabal/issues/123>`__
 134
 135   See `conf.py` for list of currently defined link shorteners.