openstack/cinder
Code Issues Proposed changes

Update doc README and remove old Makefile

Browse Source 
The information in the README file in the doc directory was very out of
date and the Makefile referenced in it doesn't appear to work any more.

Our preferred doc build method is to stay consistent with using tox -e docs,
so removing the legacy build information and providing better details for
doc development.

Change-Id: Ifd01b9cfc39fe99697a1669ecb5db6302359b662
This commit is contained in:
Sean McGinnis 2016-07-23 18:04:04 -05:00
parent 99c362bb77
commit 8d9cad38e4
2 changed files with 20 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
doc/Makefile
View File

@ -1,97 +0,0 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXSOURCE = source
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSOURCE)
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
.DEFAULT_GOAL = html
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
-rm -rf cinder.sqlite
if [ -f .autogenerated ] ; then \
cat .autogenerated | xargs rm ; \
rm .autogenerated ; \
fi
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cinder.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cinder.qhc"
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

73
doc/README.rst
View File

@ -1,66 +1,33 @@
================= =======================
Building the docs Cinder Development Docs
================= =======================
Dependencies Files under this directory tree are used for generating the documentation
============ for the Cinder source code.
Sphinx_ Developer documentation is built to:
You'll need sphinx (the python one) and if you are http://docs.openstack.org/developer/cinder/
using the virtualenv you'll need to install it in the virtualenv
specifically so that it can load the cinder modules.
:: Tools
=====
pip install Sphinx Sphinx
The Python Sphinx package is used to generate the documentation output.
Information on Sphinx, including formatting information for RST source
files, can be found in the `Sphinx online documentation
<http://www.sphinx-doc.org/en/stable/>`_.
Graphviz_ Graphviz
Some of the diagrams are generated using the ``dot`` language Some of the diagrams are generated using the ``dot`` language
from Graphviz. from Graphviz. See the `Graphviz documentation <http://www.graphviz.org/>`_
for Graphviz and dot language usage information.
::
sudo apt-get install graphviz
.. _Sphinx: http://sphinx.pocoo.org
.. _Graphviz: http://www.graphviz.org/
Use `make` Building Documentation
========== ======================
Just type make:: Doc builds are performed using tox with the ``docs`` target::
% make
Look in the Makefile for more targets.
Manually
========
1. Generate the code.rst file so that Sphinx will pull in our docstrings::
% ./generate_autodoc_index.sh > source/code.rst
2. Run `sphinx_build`::
% sphinx-build -b html source build/html
Use `tox`
=========
The easiest way to build the docs and avoid dealing with all
dependencies is to let tox prepare a virtualenv and run the
build_sphinx target inside the virtualenv::
% cd .. % cd ..
% tox -e docs % tox -e docs
The docs have been built
========================
Check out the `build` directory to find them. Yay!