Cookierelease: rename docs to doc

docs/Makefile → doc/Makefile

@@ -5,23 +5,23 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
-RELEASE = v0.1
+BUILDDIR      = build
+BASENAME      = $(subst .,,$(subst $() $(),,diffpy.nmf_mapping))
 
+# 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
 
-DOCREPONAME = <your_repo>.github.io
-DOCREPOURL  = <your_github_repo>
-
-
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
@@ -35,17 +35,20 @@ help:
 	@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)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -83,17 +86,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/fief.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/$(BASENAME).qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/fief.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/$(BASENAME).qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/fief"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/fief"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/$(BASENAME)"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/$(BASENAME)"
 	@echo "# devhelp"
 
 epub:
@@ -114,6 +117,12 @@ latexpdf:
 	$(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
@@ -158,37 +167,28 @@ doctest:
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
-push-latest:
-	cd $(BUILDDIR) && \
-	test -d $(DOCREPONAME) || git clone $(DOCREPOURL) $(DOCREPONAME) && \
-	cd $(DOCREPONAME) && \
-	git pull origin gh-pages && \
-	test -d latest || mkdir latest && touch latest/_ && \
-	rm -r latest/* && \
-	cp -r ../html/* latest/ && \
-	git add latest/ && \
-	git commit -am "Pushed latest docs at $(date)" && \
-	git push
-
-push-release:
-	cd $(BUILDDIR) && \
-	test -d $(DOCREPONAME) || git clone $(DOCREPOURL) $(DOCREPONAME) && \
-	cd $(DOCREPONAME) && \
-	git pull origin gh-pages && \
-	test -d $(RELEASE) || mkdir $(RELEASE) && touch $(RELEASE)/_ && \
-	rm -r $(RELEASE)/* && \
-	cp -r ../html/* $(RELEASE)/ && \
-	git add $(RELEASE)/ && \
-	git commit -am "Pushed $(RELEASE) docs at $(date)" && \
-	git push
-
-push-root:
-	cd $(BUILDDIR) && \
-	test -d $(DOCREPONAME) || git clone $(DOCREPOURL) $(DOCREPONAME) && \
-	cd $(DOCREPONAME) && \
-	git pull origin gh-pages && \
-	rm -rf libref previous _sources _static *.html *.js *.inv  && \
-	cp -r ../html/* . && \
-	git add . && \
-	git commit -am "Pushed root-level docs at $(date)" && \
-	git push
+# Manual publishing to the gh-pages branch
+
+GITREPOPATH = $(shell cd $(CURDIR) && git rev-parse --git-dir)
+GITREMOTE = origin
+GITREMOTEURL = $(shell git config --get remote.$(GITREMOTE).url)
+GITLASTCOMMIT = $(shell git rev-parse --short HEAD)
+
+publish:
+	@test -d build/html || \
+	    ( echo >&2 "Run 'make html' first!"; false )
+	git show-ref --verify --quiet refs/heads/gh-pages || \
+	    git branch --track gh-pages $(GITREMOTE)/gh-pages
+	test -d build/gh-pages || \
+	    git clone -s -b gh-pages $(GITREPOPATH) build/gh-pages
+	cd build/gh-pages && \
+	    git pull $(GITREMOTEURL) gh-pages
+	rsync -acv --delete --exclude=.git --exclude=.rsync-exclude \
+	    --exclude-from=build/gh-pages/.rsync-exclude \
+	    --link-dest=$(CURDIR)/build/html build/html/ build/gh-pages/
+	cd build/gh-pages && \
+	    git add --all . && \
+	    git diff --cached --quiet || \
+	    git commit -m "Sync with the source at $(GITLASTCOMMIT)."
+	cd build/gh-pages && \
+	    git push origin gh-pages

doc/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=PackagingScientificPython
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

doc/source/api/diffpy.nmf_mapping.example_package.rst

@@ -0,0 +1,31 @@
+.. _example_package documentation:
+
+|title|
+=======
+
+.. |title| replace:: diffpy.nmf_mapping.example_package package
+
+.. automodule:: diffpy.nmf_mapping.example_package
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+|foo|
+-----
+
+.. |foo| replace:: diffpy.nmf_mapping.example_package.foo module
+
+.. automodule::  diffpy.nmf_mapping.example_package.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+|bar|
+-----
+
+.. |bar| replace:: diffpy.nmf_mapping.example_package.bar module
+
+.. automodule:: diffpy.nmf_mapping.example_package.foo
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/source/api/diffpy.nmf_mapping.rst

@@ -0,0 +1,30 @@
+:tocdepth: -1
+
+|title|
+=======
+
+.. |title| replace:: diffpy.nmf_mapping package
+
+.. automodule:: diffpy.nmf_mapping
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   diffpy.nmf_mapping.example_package
+
+Submodules
+----------
+
+|module|
+--------
+
+.. |module| replace:: diffpy.nmf_mapping.example_submodule module
+
+.. automodule:: diffpy.nmf_mapping.example_submodule
+    :members:
+    :undoc-members:
+    :show-inheritance: