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>

diff --git a/docs/config.rst b/docs/config.rst
new file mode 100644 (file)
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
+<http://www.sphinx-doc.org/en/stable/config.html>`_.

diff --git a/docs/index.rst b/docs/index.rst
index ed3e99f..43b24dd 100644 (file)
--- 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 (file)
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 (file)
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 <lfdocs-conf-config>`.
+
+#. 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 <lfdocs-conf-config>`.
+
+#. 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
+   <http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role>`_ 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
+      <http://www.sphinx-doc.org/en/stable/rest.html>`_.
+
+#. (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 (file)
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