From 8d9cad38e470bed520669f454c444e8292418c46 Mon Sep 17 00:00:00 2001 From: Sean McGinnis Date: Sat, 23 Jul 2016 18:04:04 -0500 Subject: [PATCH] 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 --- doc/Makefile | 97 -------------------------------------------------- doc/README.rst | 73 +++++++++++-------------------------- 2 files changed, 20 insertions(+), 150 deletions(-) delete mode 100644 doc/Makefile diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index ba789b5df85..00000000000 --- a/doc/Makefile +++ /dev/null @@ -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 ' where 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." diff --git a/doc/README.rst b/doc/README.rst index 02fc8eb54d5..a2d171d1af5 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -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 + `_. -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 `_ + 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!