Browse Source

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
changes/15/64615/3
Andreas Jaeger 7 years ago
parent
commit
93be0e5e62
9 changed files with 214 additions and 1 deletions
  1. +1
    -1
      README.rst
  2. +89
    -0
      doc/source/conf.py
  3. +24
    -0
      doc/source/index.rst
  4. +12
    -0
      doc/source/installation.rst
  5. +71
    -0
      doc/source/man/openstack-doc-test.rst
  6. +1
    -0
      doc/source/readme.rst
  7. +7
    -0
      doc/source/usage.rst
  8. +8
    -0
      setup.cfg
  9. +1
    -0
      test-requirements.txt

+ 1
- 1
README.rst View File

@ -1,5 +1,5 @@
OpenStack Doc Tools
+++++++++++++++++++
*******************
This repository contains tools used by the OpenStack Documentation
project.


+ 89
- 0
doc/source/conf.py View File

@ -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

+ 24
- 0
doc/source/index.rst View File

@ -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`

+ 12
- 0
doc/source/installation.rst View File

@ -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

+ 71
- 0
doc/source/man/openstack-doc-test.rst View File

@ -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 <http://wiki.openstack.org/wiki/Documentation>`__
Bugs
====
* openstack-doc-tools is hosted on Launchpad so you can view current bugs at `Bugs : openstack-manuals <https://bugs.launchpad.net/openstack-manuals/>`__

+ 1
- 0
doc/source/readme.rst View File

@ -0,0 +1 @@
.. include:: ../../README.rst

+ 7
- 0
doc/source/usage.rst View File

@ -0,0 +1,7 @@
========
Usage
========
To use openstack-doc-tools in a project::
import os_doc_tools

+ 8
- 0
setup.cfg View File

@ -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

+ 1
- 0
test-requirements.txt View File

@ -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

Loading…
Cancel
Save