Install Guide¶

Follow these steps to install lfdocs-conf:

Add lfdocs-conf to your requirements.txt
Create the docs directory in the root of your repo
Create docs/conf.py with the following contents:
```
from docs_conf.conf import *
```
Note

This is the minimal configuration for this file. Further documentation on conf.py in Configuration Documentation.
Create docs/conf.yaml with the following contents:
```
project_cfg: PROJECT
```
Replace PROJECT with the name of a project configuration for your top-level project. Eg. acumos, onap, opendaylight, opnfv, etc… See here for a list of valid projects. If you are a new project and do not yet have a defaults file then please propose a patch to the docs-conf project.

Note

This is the minimal configuration necessary to get this going further documentation on conf.yaml is available in the Configuration Documentation.

Create docs/index.rst with the following contents:

.. _my-project:

My Project
==========

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
est laborum.

Replace “my-project” and “My Project” with the name of your project.

The first line “.. _my-project:” is a special Sphinx cross-ref which is useful to allow other projects to link to arbitrary locations in your project. Create these for every section heading in your project to ensure that others can link to your project.

Note

This is the minimal configuration to get a docs page generated for your project. What you do from here is entirely up to you. Please refer to the Sphinx reStructuredText Primer.

(Optional) Copy project logo to docs/_static/logo.png

Note

The logo should be a small 64x64 png image.
(Optional) Copy a favicon to docs/_static/favicon.ico
Create a tox.ini with the following contents:
```
[tox]
minversion = 1.6
envlist =
    docs
    docs-linkcheck
skipsdist = true

[testenv:docs]
deps = -rrequirements.txt
commands =
    sphinx-build -W -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html

[testenv:docs-linkcheck]
    deps = -rrequirements.txt
    commands = sphinx-build -W -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck
```
This will configure 2 tox testenvs. The first to generate the docs and the 2nd to verify links inside of the documentation. The 2nd one is useful to ensure the documentation does not contain any broken links.

Note

The -W flag enables an option to fail the build even on warnings. This flag catches useful issues with docs and projects should strive to have their docs passing with this enabled. If setting up an existing project that has warnings that are unable to resolve now then remove this option temporarily, until such a time that the project can clean up the docs.
To test run:
```
tox -e docs
google-chrome-stable docs/_build/html/index.html
```
Note

Replace the last command with your favourite web browser to view a the generated docs.