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
This commit is contained in:
parent
90a2dd0652
commit
93be0e5e62
|
@ -1,5 +1,5 @@
|
||||||
OpenStack Doc Tools
|
OpenStack Doc Tools
|
||||||
+++++++++++++++++++
|
*******************
|
||||||
|
|
||||||
This repository contains tools used by the OpenStack Documentation
|
This repository contains tools used by the OpenStack Documentation
|
||||||
project.
|
project.
|
||||||
|
|
|
@ -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
|
||||||
|
|
|
@ -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`
|
||||||
|
|
|
@ -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
|
|
@ -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/>`__
|
|
@ -0,0 +1 @@
|
||||||
|
.. include:: ../../README.rst
|
|
@ -0,0 +1,7 @@
|
||||||
|
========
|
||||||
|
Usage
|
||||||
|
========
|
||||||
|
|
||||||
|
To use openstack-doc-tools in a project::
|
||||||
|
|
||||||
|
import os_doc_tools
|
|
@ -38,3 +38,11 @@ setup-hooks =
|
||||||
console_scripts =
|
console_scripts =
|
||||||
openstack-doc-test = os_doc_tools.doctest:main
|
openstack-doc-test = os_doc_tools.doctest:main
|
||||||
openstack-autohelp = autohelp: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
|
||||||
|
|
|
@ -2,3 +2,4 @@ coverage>=3.6
|
||||||
flake8==2.0
|
flake8==2.0
|
||||||
pep8==1.4.5
|
pep8==1.4.5
|
||||||
hacking>=0.8,<0.9
|
hacking>=0.8,<0.9
|
||||||
|
sphinx>=1.1.2,<1.2
|
||||||
|
|
Loading…
Reference in New Issue