From 93be0e5e62828bcfdd3fa2b1e40fb688ae968f95 Mon Sep 17 00:00:00 2001 From: Andreas Jaeger Date: Wed, 1 Jan 2014 19:42:58 +0100 Subject: [PATCH] Use sphinx for documentation of openstack-doc-tools Update for using sphinx package so that documentation follows the OpenStack python packaging conventions. This contains an initial man page for the openstack-doc-test tool. Change-Id: I8b8ed63c3c7bcfb58f5d8f939a79c3f7c314b969 --- README.rst | 2 +- doc/source/conf.py | 89 +++++++++++++++++++++++++++ doc/source/index.rst | 24 ++++++++ doc/source/installation.rst | 12 ++++ doc/source/man/openstack-doc-test.rst | 71 +++++++++++++++++++++ doc/source/readme.rst | 1 + doc/source/usage.rst | 7 +++ setup.cfg | 8 +++ test-requirements.txt | 1 + 9 files changed, 214 insertions(+), 1 deletion(-) create mode 100755 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 doc/source/installation.rst create mode 100644 doc/source/man/openstack-doc-test.rst create mode 100644 doc/source/readme.rst create mode 100644 doc/source/usage.rst diff --git a/README.rst b/README.rst index 720413a6..caf80adf 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ OpenStack Doc Tools -+++++++++++++++++++ +******************* This repository contains tools used by the OpenStack Documentation project. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 00000000..6af0a8e1 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,89 @@ +# -*- coding: utf-8 -*- +# 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. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- 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', + #'sphinx.ext.intersphinx', + #'oslo.sphinx' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'openstack-doc-tools' +copyright = u'2014, 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. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} + +# -- Options for manual page output ------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('man/openstack-doc-test', 'openstack-doc-test', + u'OpenStack documentation tools', + [u'OpenStack'], 1) + ] + +# If true, show URL addresses after external links. +#man_show_urls = False + diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..bb6c5e73 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,24 @@ +.. openstack-doc-tool documentation master file, created by + sphinx-quickstart on Wed Jan 1 19:40:42 2014. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to openstack-doc-tool's documentation! +======================================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + readme + installation + usage + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 00000000..fb27d945 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,12 @@ +============ +Installation +============ + +At the command line:: + + $ pip install openstack-doc-tools + +Or, if you have virtualenvwrapper installed:: + + $ mkvirtualenv openstack-doc-tools + $ pip install openstack-doc-tools diff --git a/doc/source/man/openstack-doc-test.rst b/doc/source/man/openstack-doc-test.rst new file mode 100644 index 00000000..63d05d6e --- /dev/null +++ b/doc/source/man/openstack-doc-test.rst @@ -0,0 +1,71 @@ +================== +openstack-doc-test +================== + +------------------------------------------------------ +OpenStack Validation tool +------------------------------------------------------ + +SYNOPSIS +======== + +openstack-doc-test [options] + +DESCRIPTION +=========== + +openstack-doc-test allows to test the validity of the OpenStack documentation content. + +OPTIONS +======= + + **General options** + + **--verbose** + Verbose execution. + + **--version** + Output version number. + + **-, --help** + Show help message and exit. + + **--force** + Force the validation of all files and build all books. + + **--check-build** + Try to build books using modified files. + + **--check-syntax** + Check the syntax of modified files. + + **--check-deletions** + Check that deleted files are not used. + + **--check-niceness** + Check the niceness of files, for example whitespace. + + **--check-all** + Run all checks (default if no arguments are given). + + **--ignore-errors** + Do not exit on failures. + + **--api-site** + Special handling for api-site and other API repositories + to handle WADL. + +FILES +===== + +None + +SEE ALSO +======== + +* `OpenStack Documentation `__ + +Bugs +==== + +* openstack-doc-tools is hosted on Launchpad so you can view current bugs at `Bugs : openstack-manuals `__ diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 00000000..a6210d3d --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst new file mode 100644 index 00000000..1c3a07ae --- /dev/null +++ b/doc/source/usage.rst @@ -0,0 +1,7 @@ +======== +Usage +======== + +To use openstack-doc-tools in a project:: + + import os_doc_tools diff --git a/setup.cfg b/setup.cfg index f0c6be93..ae5e3911 100644 --- a/setup.cfg +++ b/setup.cfg @@ -38,3 +38,11 @@ setup-hooks = console_scripts = openstack-doc-test = os_doc_tools.doctest:main openstack-autohelp = autohelp:main + +[build_sphinx] +source-dir = doc/source +build-dir = doc/build +all_files = 1 + +[upload_sphinx] +upload-dir = doc/build/html diff --git a/test-requirements.txt b/test-requirements.txt index e5ed4ba6..b79d0d9c 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -2,3 +2,4 @@ coverage>=3.6 flake8==2.0 pep8==1.4.5 hacking>=0.8,<0.9 +sphinx>=1.1.2,<1.2