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 #### SEE ALSO:
  23
  24 https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
  25
  26 https://www.sphinx-doc.org/en/master/usage/configuration.html
  27
  28 ---
  29 ## conf.yaml
  30 #### DESCRIPTION:
  31 Required to customize lfdocs-conf behavior.
  32 ##### SEE ALSO:
  33
  34 https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
  35
  36 ---
  37 ## requirements-docs.txt
  38 ##### DESCRIPTION:
  39 Contains the required libraries to be used by Sphinx.
  40
  41 ---
  42 ## .readthedocs.yaml
  43 ##### DESCRIPTION:
  44 Required to customize the ReadTheDocs input and output behavior. **Important:** This file is located in your {project} root directory (e.g. *doc/.readthedocs.yaml*).
  45
  46 ---
  47 ## tox.ini
  48 ##### DESCRIPTION:
  49 Required to customize different tox environments.
  50 ##### SEE ALSO:
  51 https://tox.wiki/en/latest/config.html