From 0068defb206d59ccbf718b914c159fbf30c29539 Mon Sep 17 00:00:00 2001 From: Sorin Sbarnea Date: Mon, 10 Dec 2018 12:33:05 +0000 Subject: [PATCH] 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 --- .zuul.yaml | 2 + README.md | 4 +- cspell.json | 4 +- doc/requirements.txt | 3 + doc/source/_static/img | 1 + doc/source/conf.py | 56 ++++++++++++++++++ doc/source/index.rst | 7 +++ doc/source/readme.rst | 1 + .../coats-firefox-context-search.png | Bin .../coats-log-highlight-example.png | Bin tox.ini | 7 ++- 11 files changed, 81 insertions(+), 4 deletions(-) create mode 100644 doc/requirements.txt create mode 120000 doc/source/_static/img create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/readme.rst rename {doc/source/_static/img => img}/coats-firefox-context-search.png (100%) rename {doc/source/_static/img => img}/coats-log-highlight-example.png (100%) diff --git a/.zuul.yaml b/.zuul.yaml index 71ad724..93462c9 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -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 diff --git a/README.md b/README.md index 8bd0b80..e0233d2 100644 --- a/README.md +++ b/README.md @@ -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) +foxreplace-os-logs After you install Firefox extension you can either do an one-time import of the configuration from @@ -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) +coats-log-highlight-example ## Contributing diff --git a/cspell.json b/cspell.json index b5cccc8..97d61be 100644 --- a/cspell.json +++ b/cspell.json @@ -59,6 +59,8 @@ "package-lock.json" ], "ignoreWords": [ - "I18NSPHINXOPTS" + "I18NSPHINXOPTS", + "mdinclude", + "toctree" ] } diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000..de229a3 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,3 @@ +m2r # MIT +openstackdocstheme>=1.18.1 # Apache-2.0 +sphinx>=1.6.5,!=1.6.6,!=1.6.7 # BSD diff --git a/doc/source/_static/img b/doc/source/_static/img new file mode 120000 index 0000000..5d3ea89 --- /dev/null +++ b/doc/source/_static/img @@ -0,0 +1 @@ +../../../img \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..b14b9ca --- /dev/null +++ b/doc/source/conf.py @@ -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'] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..ec1daf2 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,7 @@ +Welcome to OpenStack Coats documentation! +========================================= + +.. toctree:: + :maxdepth: 2 + + readme diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..3bd447c --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. mdinclude:: ../../README.md diff --git a/doc/source/_static/img/coats-firefox-context-search.png b/img/coats-firefox-context-search.png similarity index 100% rename from doc/source/_static/img/coats-firefox-context-search.png rename to img/coats-firefox-context-search.png diff --git a/doc/source/_static/img/coats-log-highlight-example.png b/img/coats-log-highlight-example.png similarity index 100% rename from doc/source/_static/img/coats-log-highlight-example.png rename to img/coats-log-highlight-example.png diff --git a/tox.ini b/tox.ini index 4ae7660..6edac60 100644 --- a/tox.ini +++ b/tox.ini @@ -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