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:
Andreas Jaeger
parent
90a2dd0652
commit
93be0e5e62
|
|
@ -1,5 +1,5 @@
|
|||
OpenStack Doc Tools
|
||||
+++++++++++++++++++
|
||||
*******************
|
||||
|
||||
This repository contains tools used by the OpenStack Documentation
|
||||
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 =
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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…
Reference in New Issue