examples/sphinx/README.md

   1 # Examples files
   2
   3 The examples files for a working (basic) configuration of sphinx should be used
   4 by all ONAP projects (except 'doc' project). Extend them to reflect the needs
   5 in your project. **Important:** The files relate on each other. Change them carefully!
   6
   7 We provide two directories:
   8 - **master**: Contains configuration files used in the **development branch**.
   9 - **istanbul**: Contains configuration files used in the **release branch**
  10    (e.g.'istanbul'). **Important:** You need to change the 'istanbul' entries
  11    in the files! Replace them with the name of the new release branch (e.g. 'jakarta').
  12
  13 The additional directories named *_static* and *images* and the file
  14 *index.rst* are required to make the examples buildable. In the respective
  15 directory you can execute the '*tox -e docs*' command and the build starts.
  16
  17 ---
  18 ## conf.py
  19 #### DESCRIPTION:
  20 The “build configuration file” contains (almost) all configuration needed to
  21 customize Sphinx input and output behavior.
  22 #### PATH:
  23 {project}/docs/conf.py
  24 #### SEE ALSO:
  25
  26 https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
  27
  28 https://www.sphinx-doc.org/en/master/usage/configuration.html
  29
  30 ---
  31 ## conf.yaml
  32 #### DESCRIPTION:
  33 Required to customize lfdocs-conf behavior.
  34 #### PATH:
  35 {project}/docs/conf.yaml
  36 ##### SEE ALSO:
  37
  38 https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
  39
  40 ---
  41 ## requirements-docs.txt
  42 ##### DESCRIPTION:
  43 Contains the required libraries to be used by Sphinx.
  44 #### PATH:
  45 {project}/etc/requirements-docs.txt
  46 ---
  47 ## .readthedocs.yaml
  48 ##### DESCRIPTION:
  49 Required to customize the ReadTheDocs input and output behavior. **Important:** This file is located in your {project} root directory (e.g. *doc/.readthedocs.yaml*).
  50 #### PATH:
  51 {project}/.readthedocs.yaml
  52 ---
  53 ## tox.ini
  54 ##### DESCRIPTION:
  55 Required to customize different tox environments.
  56 #### PATH:
  57 {project}/tox.ini
  58 ##### SEE ALSO:
  59 https://tox.wiki/en/latest/config.html