summaryrefslogtreecommitdiffstats
path: root/examples/sphinx/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'examples/sphinx/README.md')
-rw-r--r--examples/sphinx/README.md49
1 files changed, 30 insertions, 19 deletions
diff --git a/examples/sphinx/README.md b/examples/sphinx/README.md
index ababb3834..9d416c889 100644
--- a/examples/sphinx/README.md
+++ b/examples/sphinx/README.md
@@ -1,40 +1,51 @@
# Examples files
-Examples files for a working (basic) configuration of sphinx.
-To be used by all ONAP projects (except 'doc' project).
-Extend them to reflect the needs in your project.
+The examples files for a working (basic) configuration of sphinx should be used
+by all ONAP projects (except 'doc' project). Extend them to reflect the needs
+in your project. **Important:** The files relate on each other. Change them carefully!
We provide two directories:
- **master**: Contains configuration files used in the **development branch**.
- **istanbul**: Contains configuration files used in the **release branch**
- (e.g.'istanbul'). **Important**: You need to change the 'istanbul' entries
- in the files! Replace them with the name of the new release branch.
+ (e.g.'istanbul'). **Important:** You need to change the 'istanbul' entries
+ in the files! Replace them with the name of the new release branch (e.g. 'jakarta').
The additional directories named *_static* and *images* and the file
*index.rst* are required to make the examples buildable. In the respective
-directory you can execute the '*tox -e docs*' command and the build starts.
+directory you can execute the '*tox -e docs*' command and the build starts.
-## FILE: conf.py
-##### DESCRIPTION:
+---
+## conf.py
+#### DESCRIPTION:
The “build configuration file” contains (almost) all configuration needed to
customize Sphinx input and output behavior.
+#### SEE ALSO:
+https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
-## FILE: conf.yaml
-##### DESCRIPTION:
-todo
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+---
+## conf.yaml
+#### DESCRIPTION:
+Required to customize lfdocs-conf behavior.
+##### SEE ALSO:
-## FILE: requirements-docs.txt
-##### DESCRIPTION:
-todo
+https://docs.releng.linuxfoundation.org/projects/lfdocs-conf/en/latest/config.html
-
-## FILE: .readthedocs.yaml
+---
+## requirements-docs.txt
##### DESCRIPTION:
-todo
+Contains the required libraries to be used by Sphinx.
+---
+## .readthedocs.yaml
+##### DESCRIPTION:
+Required to customize the ReadTheDocs input and output behavior. **Important:** This file is located in your {project} root directory (e.g. *doc/.readthedocs.yaml*).
-## FILE: tox.ini
+---
+## tox.ini
##### DESCRIPTION:
-todo \ No newline at end of file
+Required to customize different tox environments.
+##### SEE ALSO:
+https://tox.wiki/en/latest/config.html \ No newline at end of file