From: Thanh Ha Date: Thu, 25 Jan 2018 16:00:03 +0000 (-0500) Subject: Add initial RST documentation X-Git-Tag: v0.2.1~13 X-Git-Url: https://gerrit.linuxfoundation.org/infra/gitweb?a=commitdiff_plain;h=refs%2Fchanges%2F29%2F8529%2F7;p=releng%2Fdocs-conf.git Add initial RST documentation Push in some initial documentation to get us started. Change-Id: I1044204ddaff54ffcd4b24393fd91038dd3e4e28 Signed-off-by: Thanh Ha --- diff --git a/docs/config.rst b/docs/config.rst new file mode 100644 index 0000000..6a616eb --- /dev/null +++ b/docs/config.rst @@ -0,0 +1,48 @@ +.. _lfdocs-conf-config: + +Configuration +============= + +lfdocs-conf reads aggregates configurations from sources to determine the +effective configuration to build Sphinx. Precedence for configuration +is as follows: + +#. project/conf.py +#. project/conf.yaml +#. docs_conf/defaults/{project_cfg}.yaml +#. docs_conf/defaults/default.yaml +#. docs_conf/__init__.py + +Typically {project_cfg}.yaml provides a common theme across related +projects. For example all subprojects within the OpenDaylight project share +the common docs_conf/defaults/opendaylight.yaml. All fields provided by +defaults are overidable via one of 2 ways. + +#. conf.yaml (preferred) +#. conf.py + +.. _lfdocs-conf-conf.yaml: + +conf.yaml +--------- + +In most cases projects should use conf.yaml to configure settings. This file +should at least configure the "project_cfg" setting which will pull the +appropriate defaults configuration for their top level project to ensure a +consistent theme across all subprojects within a project. Settings here can +override settings that you would like different from the project defaults. + +Commonly used fields are "project", "version", and "author". + +.. literalinclude:: ../examples/conf.yaml + :language: yaml + +.. _lfdocs-conf-conf.py: + +conf.py +------- + +If conf.yaml does not support a Sphinx configuration you need or you have more +complex configuration needs where Python code might be useful then you can use +conf.py. This file supports the full configuration of `Sphinx conf.py +`_. diff --git a/docs/index.rst b/docs/index.rst index ed3e99f..43b24dd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,14 +6,15 @@ lfdocs-conf Linux Foundation Sphinx documentation common configuration project. This package is a set of default configurations for Linux Foundation -projects that use Sphinx to share a common configuration. +projects that use Sphinx to share a common centralized configuration. Contents: .. toctree:: :maxdepth: 2 - install-guide + install + config Indices and tables ================== diff --git a/docs/install-guide.rst b/docs/install-guide.rst deleted file mode 100644 index f934762..0000000 --- a/docs/install-guide.rst +++ /dev/null @@ -1,2 +0,0 @@ -Install Guide -============= diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..7e3bc0b --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,72 @@ +.. _lfdocs-conf-install: + +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 :ref:`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 this project. + + .. note:: + + This is the minimal configuration necessary to get this going + further documentation on conf.yaml is available in the + :ref:`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 diff --git a/examples/conf.yaml b/examples/conf.yaml new file mode 100644 index 0000000..bfac326 --- /dev/null +++ b/examples/conf.yaml @@ -0,0 +1,28 @@ +--- +project_cfg: opendaylight +project: NetVirt +release: 1.2.3 +version: 1.2.3 +author: OpenDaylight Project +copyright: 2018, OpenDaylight Project a Series of LF Projects, LLC + +needs_sphinx: '1.6.5' +extensions: + - sphinx.ext.autodoc + - sphinx.ext.doctest + - sphinx.ext.intersphinx + - sphinx.ext.todo + - sphinx.ext.coverage + - sphinx.ext.viewcode +exclude_patterns: + - .DS_Store + - _build + - Thumbs.db +todo_include_todos: false + +html_logo: _static/logo.png +html_theme: bootstrap +html_theme_options: + bootswatch_theme: cerulean + navbar_sidebarrel: false + source_link_position: footer