diff options
| -rw-r--r-- | examples/sphinx/.readthedocs.yaml | 21 | ||||
| -rw-r--r-- | examples/sphinx/README.md | 49 | ||||
| -rw-r--r-- | examples/sphinx/istanbul/conf.yaml | 2 | ||||
| -rw-r--r-- | examples/sphinx/master/conf.yaml | 2 |
4 files changed, 53 insertions, 21 deletions
diff --git a/examples/sphinx/.readthedocs.yaml b/examples/sphinx/.readthedocs.yaml new file mode 100644 index 000000000..10453a93d --- /dev/null +++ b/examples/sphinx/.readthedocs.yaml @@ -0,0 +1,21 @@ +--- +# .readthedocs.yml +# # Read the Docs configuration file +# # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# # Required +# +version: 2 + +build: + image: latest + +python: + version: 3.7 + install: + - requirements: etc/requirements.txt + +submodules: + include: all + +sphinx: + configuration: docs/conf.py 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 diff --git a/examples/sphinx/istanbul/conf.yaml b/examples/sphinx/istanbul/conf.yaml index 44de212d1..d2e9275a9 100644 --- a/examples/sphinx/istanbul/conf.yaml +++ b/examples/sphinx/istanbul/conf.yaml @@ -2,6 +2,6 @@ project_cfg: onap project: onap -# Change this to ReleaseBranchName to modify the header +# Change this to {releasename} to modify the header default-version: istanbul # diff --git a/examples/sphinx/master/conf.yaml b/examples/sphinx/master/conf.yaml index ab5928131..747e500ce 100644 --- a/examples/sphinx/master/conf.yaml +++ b/examples/sphinx/master/conf.yaml @@ -2,6 +2,6 @@ project_cfg: onap project: onap -# Change this to ReleaseBranchName to modify the header +# Change this to {releasename} to modify the header default-version: latest # |