Adds sphinx docs

Assures that the root README.me file renders images correctly on both
GitHub and Sphinx builded docs.

This should also allow us to review doc changes on zuul by loaded
their output.

Change-Id: I6cd54be73bfe25a75296af4984821320ebad7d97
This commit is contained in:
Sorin Sbarnea 2018-12-10 12:33:05 +00:00
parent a1d15b7f64
commit 0068defb20
11 changed files with 81 additions and 4 deletions

View File

@ -9,7 +9,9 @@
- project:
check:
jobs:
- build-openstack-sphinx-docs
- openstack-tox-linters-npm
gate:
jobs:
- build-openstack-sphinx-docs
- openstack-tox-linters-npm

View File

@ -12,7 +12,7 @@ some extra coloring on build logs, making them easier to read. We plan to
convert this into a greasemonkey helper in the future to allow use from
multiple browsers.
![foxreplace-os-logs](https://raw.githubusercontent.com/openstack/coats/master/doc/source/_static/img/coats-log-highlight-example.png)
<img alt=foxreplace-os-logs src=img/coats-log-highlight-example.png width=100%>
After you install Firefox extension you can either do an one-time import
of the configuration from <https://raw.githubusercontent.com/openstack/coats/master/coats/FoxReplace.json>
@ -33,7 +33,7 @@ websites you may find useful to use [Context Search Firefox extension](https://a
allows you to perform context searches. You can import the configuration from
``coats/searchEngines.json``
![coats-log-highlight-example](https://raw.githubusercontent.com/openstack/coats/master/doc/source/_static/img/coats-log-highlight-example.png)
<img alt=coats-log-highlight-example src=img/coats-firefox-context-search.png width=100%>
## Contributing

View File

@ -59,6 +59,8 @@
"package-lock.json"
],
"ignoreWords": [
"I18NSPHINXOPTS"
"I18NSPHINXOPTS",
"mdinclude",
"toctree"
]
}

3
doc/requirements.txt Normal file
View File

@ -0,0 +1,3 @@
m2r # MIT
openstackdocstheme>=1.18.1 # Apache-2.0
sphinx>=1.6.5,!=1.6.6,!=1.6.7 # BSD

1
doc/source/_static/img Symbolic link
View File

@ -0,0 +1 @@
../../../img

56
doc/source/conf.py Normal file
View File

@ -0,0 +1,56 @@
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc',
'openstackdocstheme',
'm2r'
]
# openstackdocstheme options
repository_name = 'openstack/coats'
use_storyboard = True
bug_tag = ''
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'coats'
copyright = u'2018, OpenStack Foundation'
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'openstackdocs'
html_extra_path = ['_static']

7
doc/source/index.rst Normal file
View File

@ -0,0 +1,7 @@
Welcome to OpenStack Coats documentation!
=========================================
.. toctree::
:maxdepth: 2
readme

1
doc/source/readme.rst Normal file
View File

@ -0,0 +1 @@
.. mdinclude:: ../../README.md

View File

Before

Width:  |  Height:  |  Size: 222 KiB

After

Width:  |  Height:  |  Size: 222 KiB

View File

Before

Width:  |  Height:  |  Size: 287 KiB

After

Width:  |  Height:  |  Size: 287 KiB

View File

@ -1,6 +1,7 @@
[tox]
minversion = 2.3.1
envlist = linters
envlist = linters,docs
skipsdist = True
skip_missing_interpreters = true
[testenv]
@ -33,6 +34,10 @@ whitelist_externals =
which
xargs
[testenv:docs]
deps = -r{toxinidir}/doc/requirements.txt
commands = sphinx-build -b html -W doc/source doc/build/html
[testenv:linters]
commands=
pip install -q -r requirements.txt -r test-requirements.txt