cleaned up docs (#39)

* cleaned up docs

.gitignore

@@ -37,7 +37,7 @@ setup_env_virtualenv.sh
 .pytest_cache
 
 # sphinx
-docs/_build/
+docs/build/
 
 # IPython
 .ipynb_checkpoints

docs/releases.rst → CHANGES.rst

@@ -1,14 +1,14 @@
 Release Notes
 =============
 
-Release 0.2.2
--------------
+0.2.2 (2019-07-19)
+------------------
 
 - Fixed test suite (#33)
 - Added badges for RTD and Travis CI to Readme.
 
-Release 0.2.1
--------------
+0.2.1 (2018-03-14)
+------------------
 
 This release includes the following features:
 
@@ -17,8 +17,8 @@ This release includes the following features:
  - Works with Python 3 version of `MyProxyClient`.
  - Testing structure with `pytest` has been improved.
 
-Release 0.1.8
--------------
+0.1.8 (2017-01-03)
+------------------
 
 This release includes the following changes:
 
@@ -34,15 +34,14 @@ This release includes the following changes:
  4. Searches at the file-level now return a `gridftp_url` property along with other existing properties such
     as `download_url`.
 
-Release 0.1b1
--------------
+0.1.6 (2016-05-16)
+------------------
 
-This release marks the start of the 0.1 series which is considered beta-quality.  API changes in this series will be clearly marked in the documentation and backward-compatible releases will be maintained on pypi.
-
-The 0.1b1 release includes integrated MyProxy logon support in the :mod:`pyesgf.logon` module.  This release also includes optimisations to the search system to avoid querying multiple shards when requesting the files from a dataset.
+This release includes a fix for Issue #4 to cope with ESGF Search end points
+being given with or without a ":port" component in the host address.
 
-Release 0.1.1
--------------
+0.1.1 (2013-04-15)
+------------------
 
 This release will include wget script download support.
 
@@ -61,3 +60,10 @@ This release changes the call signature of :meth:`SearchConnection.send_query()`
 
  1. Change the *url* parameter to :meth:`SearchConnection()` to not include the ``/search`` suffix
  2. Change any occurance of :meth:`send_query()` to :meth:`send_search()`
+
+0.1b1 (2013-01-19)
+------------------
+
+This release marks the start of the 0.1 series which is considered beta-quality.  API changes in this series will be clearly marked in the documentation and backward-compatible releases will be maintained on pypi.
+
+The 0.1b1 release includes integrated MyProxy logon support in the :mod:`pyesgf.logon` module.  This release also includes optimisations to the search system to avoid querying multiple shards when requesting the files from a dataset.

Makefile

@@ -64,7 +64,7 @@ coverage: ## check code coverage quickly with the default Python
 docs: ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
-	$(BROWSER) docs/_build/html/index.html
+	$(BROWSER) docs/build/html/index.html
 
 servedocs: docs ## compile the docs watching for changes
 	watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .

README.rst

@@ -27,11 +27,11 @@ You can try it online using Binder, or view the notebooks on NBViewer.
    :height: 20
 
 Please submit bugs and feature requests through the bug tracker on
-github_. Pull requests are always welcome.
+GitHub_. Pull requests are always welcome.
 
 Full documentation_ is available on ReadTheDocs or in the docs directory.
 
 .. _`Earth System Grid Federation`: https://esgf.llnl.gov/
 .. _`ESGF Search API`: https://github.com/ESGF/esgf.github.io/wiki/ESGF_Search_REST_API
 .. _documentation: http://esgf-pyclient.readthedocs.org
-.. _`github`: https://github.com/ESGF/esgf-pyclient
+.. _GitHub: https://github.com/ESGF/esgf-pyclient

docs/Makefile

@@ -5,16 +5,21 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -25,21 +30,26 @@ help:
 	@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 "  applehelp  to make an Apple Help Book"
 	@echo "  devhelp    to make HTML files and a Devhelp project"
 	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
 	@echo "  texinfo    to make Texinfo files"
 	@echo "  info       to make Texinfo files and run them through makeinfo"
 	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -69,25 +79,29 @@ json:
 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."
+	@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/ESGFPyclient.qhcp"
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Birdy.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/ESGFPyclient.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Birdy.qhc"
+
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" 	      "~/Library/Documentation/Help or install it in your application" 	      "bundle."
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/ESGFPyclient"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/ESGFPyclient"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Birdy"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Birdy"
 	@echo "# devhelp"
 
 epub:
@@ -99,15 +113,20 @@ latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" 	      "(use \`make latexpdf' here to do that automatically)."
 
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
@@ -122,8 +141,7 @@ texinfo:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
 	@echo
 	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
+	@echo "Run \`make' in that directory to run these through makeinfo" 	      "(use \`make info' here to do that automatically)."
 
 info:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@@ -144,10 +162,22 @@ 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."
+	@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."
+	@echo "Testing of doctests in the sources finished, look at the " 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " 	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/source/api.rst

@@ -0,0 +1,33 @@
+.. _api:
+
+#############
+API Reference
+#############
+
+.. contents::
+    :local:
+    :depth: 1
+
+
+Search API
+==========
+
+.. automodule:: pyesgf.search
+   :members:
+
+.. automodule:: pyesgf.search.connection
+   :members:
+
+.. automodule:: pyesgf.search.context
+   :members:
+
+.. automodule:: pyesgf.search.results
+   :members:
+
+ESGF Security API
+=================
+
+:mod:`pyesgf` provides a simplified interface to obtaining ESGF credentials.
+
+.. automodule:: pyesgf.logon
+   :members:

docs/source/changes.rst

@@ -0,0 +1 @@
+.. include:: ../../CHANGES.rst

docs/concepts.rst → docs/source/concepts.rst

@@ -1,3 +1,7 @@
+###############
+Design Concepts
+###############
+
 Search Concepts
 ===============
 

docs/conf.py → docs/source/conf.py

@@ -14,7 +14,7 @@
 import sys
 import os
 
-sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('../../'))
 from pyesgf import __version__ as pyesgf_version
 
 # If extensions (or modules to document with autodoc) are in another directory,