Update doc README and remove old Makefile
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
parent
99c362bb77
commit
8d9cad38e4
97
doc/Makefile
97
doc/Makefile
@ -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."
|
||||
@ -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_
|
||||
You'll need sphinx (the python one) and if you are
|
||||
using the virtualenv you'll need to install it in the virtualenv
|
||||
specifically so that it can load the cinder modules.
|
||||
Developer documentation is built to:
|
||||
http://docs.openstack.org/developer/cinder/
|
||||
|
||||
::
|
||||
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
|
||||
from Graphviz.
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install graphviz
|
||||
|
||||
.. _Sphinx: http://sphinx.pocoo.org
|
||||
|
||||
.. _Graphviz: http://www.graphviz.org/
|
||||
from Graphviz. See the `Graphviz documentation <http://www.graphviz.org/>`_
|
||||
for Graphviz and dot language usage information.
|
||||
|
||||
|
||||
Use `make`
|
||||
==========
|
||||
Building Documentation
|
||||
======================
|
||||
|
||||
Just type make::
|
||||
|
||||
% 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::
|
||||
Doc builds are performed using tox with the ``docs`` target::
|
||||
|
||||
% cd ..
|
||||
% tox -e docs
|
||||
|
||||
|
||||
The docs have been built
|
||||
========================
|
||||
|
||||
Check out the `build` directory to find them. Yay!
|
||||
|
||||
Loading…
Reference in New Issue
Block a user