Add support for sphinx-tabs extension

This extension allows us to use code tabs in docs.

Change-Id: I5e57e5056d5b6abc05842aa37ad6b7fadfe94ca8
Ref: https://github.com/djungelorm/sphinx-tabs
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Merge "Update Sphinx to 3.0.4"

Merge "Update pre-commit hooks 2020-06"

Update Sphinx to 3.0.4

Update docs-conf to use the latest Sphinx 3.0.4.

Change-Id: Ic44e8d44a0c68f5f3727f3e1b3ee3368b45d6cd2
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Make GitLint actually run as part of pre-commit

The tox environment for pre-commit currently does not actually run
the gitlint hook.

Change-Id: Idbb1f8878dfbc387468dcf9dc874f21a25ffa856
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Print git-diff when pre-commit fails

When pre-commit fails and automatically fixes issues for us in Jenkins
we are not able to see what pre-commit automatically fixed. Adding
--show-diff-on-failure makes pre-commit perform a git-diff immediately
after failing to ensure more useful output is printed to inform the
contributor what changes are needed to pass the check.

Change-Id: I5553c09d6079a71d64eebf3058e0cdec5fdf6b4f
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Update pre-commit hooks 2020-06

It's been awhile since we last updated these hooks so let's catch
up with the world.

Change-Id: Ic3fec646f659403b8893134b49320984d412639c
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Bump OPNFV Copyright to 2020

Update the OPNFV documentation copyright to 2020.

Change-Id: Ib96ccffce461e57c9ce8d5943021ed0921eec89b
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Update Sphinx and bootstrap theme versions

Change-Id: Id81f717315470f9d6dbda5c074c6a1c405c6eefe
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Upgrade sphinx version to 2.2.2

sphinx-build breaks with osx when using the -j flag
for parallel builds, but is handled in v2.2.2:

https://www.sphinx-doc.org/en/master/changes.html

Signed-off-by: Jamo Luhrsen <jluhrsen@gmail.com>
Change-Id: Iaf218a41d8d8ac7b9b014ead0c2c8e117fb83027

Add onap

Add section for onap
with onap specific configs
taken from
onap/doc/docs/conf.py

Signed-off-by: Aric Gardner <agardner@linuxfoundation.org>
Change-Id: I0655f21db43a2111db0477f98c592de4d420f850

Add Oran

Oran documentation is WIP
I will need this released
before we can complete this task

Signed-off-by: Aric Gardner <agardner@linuxfoundation.org>
Change-Id: I3db6fc6644bc9f1f39e8cc6a8918b876902bcefd

Configure basepython to python3

More and more libraries that we are pulling in require Python 3 so
to avoid having to play the pin dependencies whack-a-mole game let's
bump or base python where possible to python3.

Change-Id: Ib25f0290675d2855ed29905331eb76ecbe39fdbf
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Pin pygments to 2.3.x

Pygments released 2.4.0 which added a python requires that excludes all
versions of Python < 3.5. The LFCI's default Python 3 version is 3.4 so
causes build failure.

Change-Id: Iecf065ccbc9de7782b64955c1cd904dfb1c16b8a
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Replace coala commit-msg hook with pre-commit

Idea here is to replace the slow coala checker with the
much faster pre-commit hooks in the future as we replace
the different linters we're using via coala with pre-commit
versions.

Using this requires the developer to setup pre-commit on their
local dev environment to initialize this the first time the
contribute to this repo.

Install can be performed via one of the following methods:

1) Install pre-commit from your local package manager then run:

    pre-commit install --hook-type commit-msg

2) Run `tox -e check-hooks`

Change-Id: I5b5d3dcbd7d83e90322f63ba99fa1f76c88ee8ad
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Add docs-linkcheck to test links

Change-Id: I83e718791c22311be0d96dd9137308a79c9fd14a
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Update Sphinx cfg to use modern features from 1.8

* Enable --keep-going mode to fail at end after all warnings printed
* Use parallel auto mode
* Remove unnecessary echo command

Change-Id: I391d5fcc6675d78b0880c01e711b6749cc8174ec
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Update Sphinx to version ~1.8

Sphinx 1.8 introduces a `--keep-going` parameter which will be handy
for our docs project so that it prints out all docs failures before
failing the build. This allows CI resources to not be wasted by only
printing one failure at a time.

Change-Id: I62c77a94f735fddcb8939aa5dbeb84566ae75d86
Signed-off-by: Thanh Ha <zxiiro@gmail.com>

Update Python link to save redirect

This resolves the message we keep seeing when building docs that says
"intersphinx inventory has moved:" for this link.

Change-Id: Ia386c56ba0be2652acf7b34fa6a280ef52918150
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

pin more-intertools

Version 6.0.0 is a Python 3-only release
https://github.com/erikrose/more-itertools/releases

error form docs build:
more-itertools requires Python '>=3.4' but the running Python is 2.7.5

Change-Id: I6fa0b0e2bf96bfd66a3980d319570325b51666b9
Signed-off-by: Aric Gardner <agardner@linuxfoundation.org>

Pull version strings from PBR

We've been using PBR for awhile but never updated the docs config to
get it's versioning info from it.

Change-Id: I0884ab9835c0cb763395fc877d04fb0f8ad488b9
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Use reno for release notes

Change-Id: I9f08ef7c04f815203ec3a0aba8284f9ea187cf77
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Release lfdocs-conf v0.2.5

Change-Id: I60bf2e7dbff7c58785016d6db29b1dd2c1b56b43
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Move docs reqs back to reqs.txt

We actually depend on lfdocs-conf to ship Sphinx to downstream
consumers removing it from requirements.txt was a bad idea.

Move it back and use skip_install=True in coala to have it skip
installing requirements.txt in the coala testenv.

Change-Id: Ia0739405a4b68dcdb1ca509701745b6dc9828588
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Release lfdocs-conf v0.2.4

Change-Id: I0a29d69864eb734525860538c8bb4b1e1091a410
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Pin Sphinx to version <1.8.0

The new 1.8.0 release of Sphinx is breaking builds in our CI.

In order to get tox runs to pass, the requirement files need to be split
apart and Sphinx version explicitly set for coala. This is due to some
coala bear requiring a version of Sphinx <1.5, which appears to get
pulled in from the base requirements.txt file.

This patch also includes minor clean up of the tox.ini file and a
pyflake validation fix.

Change-Id: Iea9b870270d7a8954f611aaca451de653397397a
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Merge "Setup universal wheel"

Add PBR files to .gitignore

Change-Id: I1eefa26c0f62a913150bb2dcea359db5806f2d9e
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Setup universal wheel

Change-Id: I6d868fa70b5843492458ef3754b859e8fd2b47dd
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Setup PBR

Change-Id: I51d260da9f38fba8851d4d8e72976209f332d842
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Bump lfdocs-conf to 0.3.0-dev

Change-Id: I252780c0c4dcd7ab54e2dbda948e2f1d76a53bf7
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Release lfdocs-conf v0.2.3

Change-Id: I595f9dcfd47ec0566cbbeaf7dc2474e4a925b5ac
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Merge "Add "skipsdist = true" to tox.ini"

Remove echo of docs path

Since Sphinx 1.7.x Sphinx actually prints the path itself now
so we no longer need this explicit statement.

Change-Id: If2947ac6921fdefb3e51f1910a8f6819ffcf0d52
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add "skipsdist = true" to tox.ini

Most of our projects using Sphinx are not Python projects so
building sdist does not make sense for them. Default docs to
skip it since folks working on Python projects are more likely
to know what this parameter means.

Change-Id: Ib38395954c2fba988480cd5774b0e7ac46499b91
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add pre-commit hook for trailing-whitespace

Install using tox:

    tox -e check-hooks

ref: https://pre-commit.com

Change-Id: I80ac7933ee3d350c3d3d860e190b8348efd701e1
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Update lfdocs links to https

Save us on redirects when fetching the links.

Change-Id: Ic0d5290159a4af5bea54444ba4f106cc28ce3480
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Release lfdocs-conf v0.2.2

Change-Id: Ie6d8b97d96050553daa6df0b05d3b9500d438216
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Merge "Add flag to fail with warnings in instructions"

Add common-packer intersphinx mapping

Mapping allows all projects that use lfdocs-conf to be able to
intersphinx with CP without needing to add it to their local
conf.py config.

Change-Id: Icd4e36cc1391c881e3cbb083afc611792a9a4595
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add flag to fail with warnings in instructions

This is good practice so let's make sure our instructions set this
by default with a note in case a project is not ready for such a
configuration.

Change-Id: Ia71ca45af4e219c3eb50667772addbf77a584a82
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Bump version to 0.3.0-dev

Change-Id: I6561658d5b2194f456865bd2cb729bada2e0e30a
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Fail Sphinx build even on warnings

Change-Id: I5a6d6827870ff680cfc54c7aea171f1ce544a753
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Release lfdocs-conf v0.2.1

Change-Id: Ia1e8293e7fccf4ed1d02342c15b1197797ab0c9c
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Set _static defaults for LF Projects

Commit: 255554fd868f98da0b8e3a7b9cec959cc7945b59 change the defaults for
'html_favicon', 'html_static_path', and 'html_logo', but did not push
them into LF projects that use them.

Change-Id: I46b5256485443905a520c959e217297901548039
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Release lfdocs-conf v0.2.0

Change-Id: I10a435c092a5a8db9fd046a7a0c1bc7336e3a7ed
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Merge "Default release to version if not in use"

Use Sphinx defaults when config values are missing

More of these should be verified and moved into defaults.yaml where it
makes sense. We should not change those that make sense such as
'source_suffix', and 'master_doc'.

Change-Id: Iced9fbe6ddd20145d8aa354fdef5edb0638dbbdb
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Fix capitalization for Sphinx requirement

Change-Id: I92b089c74f49bcc9d10ec31e2d6a9e500e0803d6
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Default release to version if not in use

Simplify things by setting release = version for projects who do
not have the clear distinction.

Change-Id: I746f599ffc10012003c4268b1b31094bcaee5a6f
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Update URL listed in setup.py

The current URL 404s while the new URL lists the project patchsets.

Change-Id: I0a9793db118fe60e56db18e624ff59f4336d7daf
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Merge "Add missing links to docs-conf and valid defaults"

Merge "Update OPNFV Defaults"

Merge "Conditionally import OPNFV Theme"

Add missing links to docs-conf and valid defaults

- Link to a list of valid projects
- Link to docs-conf project

Change-Id: I3c0fbd4065a0f3aaf13e15282a9d025f04de3498
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add details on what to include in tox.ini

Missing information on adding a tox.ini so that the docs can
be generated and tested via `tox -e docs` command.

Change-Id: I900137817032e77109d891c7a194d3f956b1b278
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add a step to test the docs generation

Includes details on how to test and review the docs locally.

Change-Id: I0eb3761d0738ee511439b42bb107737fbd517d1b
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Conditionally import OPNFV Theme

When using the 'opnfv' theme, conf.py needs to run the Python code
'sphinx_opnfv_theme.get_html_theme_path()' in order
to determine the location of package data on the filesystem.

Instead of having every project that wants to use the OPNFV theme set
this explicitly in their conf.py, we conditionally import the theme and
execute the code.

Change-Id: Ic686483fd511bf5e321977c2802f4cfb8986c800
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Update OPNFV Defaults

Configures the theme and an extra theme option along with updating the
copyright year and holder to match the current documentation.

Change-Id: Ifff21bd9782112419b8c209fba8d27f1dd7b3a90
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Add opendaylight defaults

Change-Id: I8e3ebf8ad5917f5642519b2fea96f0db8861eecd
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add initial RST documentation

Push in some initial documentation to get us started.

Change-Id: I1044204ddaff54ffcd4b24393fd91038dd3e4e28
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add favicon.ico

Change-Id: I10cb9c8dd48431ce8ce7b7cdf9dc1ffd6209844a
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add Documentation linting

Change-Id: I6e1cfebca8289549222e0879ca30f67067561484
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Remove weasel word

Change-Id: I80e97aa6c7b5ad75dc899222eac2ce1335820016
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Enable YAMLLint

Change-Id: I42ee8edd5994126461636ea9d349ae912a9e6e13
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Fix YAMLLint issues

Change-Id: I3c450edada171a8e4e3c3da19cd46f1985c6ecf7
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Fix precedent listing to include 'defaults' path

Change-Id: I6a77f5f5524b9fc98f17d72cd59cb5c72e34efcb
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Add YAML Header to Docs conf.yaml

Change-Id: Ie9c959b551842c370cff83f361439c817f5146d3
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

Update intersphinx mapping URLs

Change-Id: I6930999cb1e643407a49a9eff033bcb32ad1b874
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Set default logo location to _static/logo.png

Let's standardize to a simple location. Projects can override
this in their own paths.

Change-Id: I8992eb3629219a356631e211e954c080c5c52e83
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Default to Sphinx 1.6.5

Change-Id: Ib7f60954095b0569992a20b7833cc844e6d36f27
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Require sphinx 1.6.5

Read The Docs has sphinx 1.6.5 installed so lets require that
as minimum to avoid having to put in workarounds for that.

Change-Id: I33e11cd9f687e2bf93aaf38a02e2c11cc640ad64
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Move code out of __init__ and into conf.py module

This allows us to use __init__.py to store __version__ and other
metadata strings and be reused in local documentation and setup.py
to shore a single version file.

The problem with having code in __init__.py is that the code will
be executed even if all the documentation code wants to pull is the
metadata variable.

Change-Id: I7382c81508be42a41c99f392f8006cfdf9887258
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add sys path for rtd

Change-Id: I820fc0e5d183088a1128ab84f2d11fd3b32a0268
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Update Python linter to lint all docs_conf code

Also resolve lint issues.

Change-Id: Ifab8d9c3c3cfffab8609cc0740862f2718986aa6
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Initialize Sphinx documentation

Change-Id: I814be3e544a45b96e9a882fc52f248cdeccb146d
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Add missing license headers

Change-Id: I0559ce5115d2bd3157b4d329455f434afd19f35e
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Initial Commit of Sphinx Config project

Creates a lfdocs-conf package that is pip installable.

The minimal conf.yaml consists of only a project_cfg configuration
with the name of the project eg opendaylight, opnfv, lfdocs:

   ---
   project_cfg: lfdocs

Limitations:

intersphinx_mapping is not currently mappable via yaml due to
it being a complex data set of a tuple + data type (None). Projects
can override this by setting it in their local conf.py or accept the
defaults provided by the lfdocs-conf project.

Change-Id: Ia695047dc92adc00e4e9ec1f6d3ed824d10c0959
Co-authored-by: Thanh Ha <thanh.ha@linuxfoundation.org>
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Bootstrap docs-conf project

Change-Id: I7e23f8be866f79d4e410b6e8628d33c6377b8b33
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

Initial empty repository