Add files for sphinx

CHANGELOG.rst

@@ -0,0 +1,2 @@
+* :release:`0.2.0 <2017-03-10>`
+* :feature:`0` This is the first official release 

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -j4
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build

docs/changelog.rst

@@ -0,0 +1,7 @@
+.. _changelog:
+
+*********
+Changelog
+*********
+
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -8,19 +8,32 @@
 
 import sys
 import os
+import shutil
 #import matplotlib as mpl
 #mpl.use("Agg")
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 
-sys.path.insert(0, os.path.abspath('sphinxext'))
+ABIFLOWS = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), ".."))
+print("ABIFLOWS", ABIFLOWS)
+
+sys.path.insert(0, ABIFLOWS)
 
 import imp
-mod_name = "../abiflows/core/release.py"
+mod_name = os.path.join(ABIFLOWS, "abiflows", "core", "release.py")
 relmod = imp.load_source(mod_name, mod_name)
 
+on_rtd = os.environ.get('READTHEDOCS') == 'True' and os.environ.get("READTHEDOCS_PROJECT")
+#if on_rtd:
+#    print("Preparing execution on READTHEDOCS server...")
+#    os.makedirs(os.path.expanduser("~/.abinit/abipy"))
+#    shutil.copy(os.path.join(ABIFLOWS, "data", "managers", "travis_scheduler.yml"),
+#                os.path.expanduser("~/.abinit/abipy/scheduler.yml"))
+#    shutil.copy(os.path.join(ABIFLOWS, "data", "managers", "travis_manager.yml"),
+#                os.path.expanduser("~/.abinit/abipy/manager.yml"))
+
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -31,7 +44,6 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
-    #'sphinx.ext.coverage',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
@@ -46,13 +58,15 @@
     #'sphinx_gallery.gen_gallery',
     #"sphinxarg.ext",         # CLI doc
     #'nbsphinx',
+    'sphinxcontrib.bibtex',
+    "releases",
 ]
 
 # Add any Sphinx extension module names here, as strings. They can
 # be extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 import matplotlib
 extensions += [
-    'matplotlib.sphinxext.mathmpl',
+    #'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.only_directives',
     'matplotlib.sphinxext.plot_directive',
     'IPython.sphinxext.ipython_directive',
@@ -114,7 +128,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '**.ipynb_checkpoints']
+exclude_patterns = ['_build', '**.ipynb_checkpoints', "links.rst"]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -363,9 +377,51 @@
     "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
     'pandas': ("http://pandas-docs.github.io/pandas-docs-travis/", None),
     'matplotlib': ('http://matplotlib.org/', None),
+    "monty": ("http://pythonhosted.org/monty/", None),
     "pymatgen": ("http://pymatgen.org/", None),
+    "fireworks": ("https://materialsproject.github.io/fireworks/", None),
+    "abipy": ("http://pythonhosted.org/abipy/", None),
 }
 
 # If true, Sphinx will warn about all references where the target cannot be found.
 # Default is False. You can activate this mode temporarily using the -n command-line switch.
 #nitpicky = True
+
+# A string of reStructuredText that will be included at the end of every source file that is read.
+# This is the right place to add substitutions that should be available in every file.
+with open("links.rst", "rt") as fh:
+    rst_epilog = fh.read()
+
+# http://www.sphinx-doc.org/en/stable/ext/extlinks.html#confval-extlinks
+# :abivar:`ecut`
+#ABINIT_DOCS_URL =
+#extlinks = {'
+#    "abivar" : (ABINIT_DOC_ULRS + '/abinit/%s', "")
+#    api_url' : (settings.BASE_URL + '%s', settings.BASE_URL)
+#}
+
+autodoc_member_order = "bysource"
+
+#'members', 'undoc-members', 'private-members', 'special-members', 'inherited-members' and 'show-inheritance'.
+#autodoc_default_flags = ["show-inheritance", "inherited-members", "special-members"]
+
+# From https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#custom-formatting-sorting-and-labelling
+# pybtex provides a very powerful way to create and register new styles, using setuptools entry points,
+# as documented here: http://docs.pybtex.org/api/plugins.html
+
+#from pybtex.style.formatting.unsrt import Style as UnsrtStyle
+#from pybtex.style.template import toplevel # ... and anything else needed
+#from pybtex.plugin import register_plugin
+#
+#class MyStyle(UnsrtStyle):
+#
+#    def format_XXX(self, e):
+#        template = toplevel [
+#            # etc.
+#        ]
+#        return template.format_data(e)
+#
+#register_plugin('pybtex.style.formatting', 'mystyle', MyStyle)
+
+# This is for releases http://releases.readthedocs.io/en/latest/usage.html
+releases_github_path = "abinit/abipy"

docs/index.rst

@@ -1,5 +1,4 @@
 .. htmlonly::
-
     :Release: |version|
     :Date: |today|
 
@@ -24,7 +23,8 @@ Getting Started
 
    features
    installation
-   whats_new
+   changelog
+   zzbiblio
 
 
 API

docs/installation.rst

@@ -2,6 +2,9 @@
 Getting AbiFlows
 ================
 
+.. contents::
+   :backlinks: top
+
 --------------
 Stable version
 --------------

docs/links.rst

@@ -0,0 +1,119 @@
+.. Links to websites
+.. _Sphinx: http://sphinx.pocoo.org
+.. _Abinit: https://www.abinit.org
+.. _abiconfig: https://github.com/abinit/abiconfig
+.. _abiflows: https://github.com/abinit/abiflows
+.. _abitutorials: https://github.com/abinit/abitutorials
+.. _abiconda: https://github.com/abinit/abiconda
+.. _pseudo-dojo: http://www.pseudo-dojo.org/
+.. _pseudo-dojo repository: https://github.com/abinit/pseudo_dojo
+.. _pymatgen: http://www.pymatgen.org
+.. _fireworks: https://materialsproject.github.io/fireworks/
+.. _mongodb: https://www.mongodb.com/
+.. _mongoengine: http://mongoengine.org/
+.. _`materials project`: https://materialsproject.org/
+.. _conda: https://conda.io/docs/
+.. _Anaconda: https://continuum.io/downloads
+.. _abinit-channel: https://anaconda.org/abinit
+.. _matsci: http://materials.sh/
+.. _spack: https://github.com/LLNL/spack
+.. _matplotlib: http://matplotlib.org
+.. _pandas: http://pandas.pydata.org
+.. _scipy: https://www.scipy.org/
+.. _numpy: http://www.numpy.org/
+.. _seaborn: https://seaborn.pydata.org/
+.. _simpy: https://simpy.readthedocs.io/en/latest/
+.. _networkx: https://networkx.github.io/
+.. _pytest: https://docs.pytest.org/en/latest/contents.html
+.. _netcdf4-python: http://unidata.github.io/netcdf4-python/
+.. _nbformat: https://github.com/jupyter/nbformat
+.. _pip: https://pypi.python.org/pypi/pip
+.. _ipython: https://ipython.org/index.html
+.. _jupyter: http://jupyter.org/
+.. _Python: http://www.python.org/
+.. _spglib: https://atztogo.github.io/spglib/
+.. _bader: http://theory.cm.utexas.edu/henkelman/code/bader/
+.. _ase: https://wiki.fysik.dtu.dk/ase/
+.. _COD: http://www.crystallography.net/cod/
+.. _CIF: http://www.iucr.org/resources/cif
+.. _vesta: http://jp-minerals.org/vesta/en/
+.. _xcrysden: http://www.xcrysden.org/
+.. _xmgrace: http://plasma-gate.weizmann.ac.il/Grace/
+.. _gnuplot: http://www.gnuplot.info/
+.. _ovito: https://ovito.org/
+.. _v_sim: http://inac.cea.fr/L_Sim/V_Sim/
+.. _mayavi: http://docs.enthought.com/mayavi/mayavi/
+.. _avogadro: https://avogadro.cc/
+.. _nbjsmol: https://github.com/gmatteo/nbjsmol
+.. _phononwebsite: http://henriquemiranda.github.io/phononwebsite/
+.. _phonopy: https://atztogo.github.io/phonopy/
+.. _netcdf: https://www.unidata.ucar.edu/software/netcdf/docs/faq.html#whatisit
+.. _ipywidgets: https://github.com/jupyter-widgets/ipywidgets
+.. _YAML: https://en.wikipedia.org/wiki/YAML
+.. _JSON: https://en.wikipedia.org/wiki/JSON
+.. _slurm: https://slurm.schedmd.com/
+.. _pbspro: http://pbspro.org/
+.. _sge: http://gridscheduler.sourceforge.net/howto/GridEngineHowto.html
+.. _torque: http://www.adaptivecomputing.com/products/open-source/torque/
+.. _moab: http://www.adaptivecomputing.com/products/hpc-products/moab-hpc-basic-edition/
+.. _loadleveler: https://www.ibm.com/support/knowledgecenter/en/SSFJTW
+
+.. Links to important python objects.
+.. _POSCAR: http://cms.mpi.univie.ac.at/vasp/guide/node59.html
+.. _DataFrame: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html
+.. _DataFrames: https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html
+
+.. Links to jupyter notebooks associated to AbiPy files available at
+   https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/index.ipynb?flush_cache=true
+.. _AbipyStructure: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/structure.ipynb
+.. _AbinitInput: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/abinit_input.ipynb
+.. _GSR.nc: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/gsr.ipynb
+.. _HIST.nc: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/hist.ipynb
+.. _FATBANDS.nc: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/efatbands.ipynb
+.. _DDB: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/ddb.ipynb
+.. _SIGRES.nc: https://nbviewer.jupyter.org/github/abinit/abitutorials/blob/master/abitutorials/sigres.ipynb
+
+.. Important Abipy objects.
+.. |AttrDict| replace:: :class:`monty.collections.AttrDict`
+.. |Function1D| replace:: :class:`abipy.core.func1d.Function1D`
+.. |Mesh3d| replace:: :class:`abipy.core.mesh3d.Mesh3d`
+.. |GSphere| replace:: :class:`abipy.core.gsphere.GSphere`
+.. |Kpoint| replace:: :class:`abipy.core.kpoints.Kpoint`
+.. |KpointList| replace:: :class:`abipy.core.kpoints.KpointList`
+.. |Kpath| replace:: :class:`abipy.core.kpoints.Kpath`
+.. |IrredZone| replace:: :class:`abipy.core.kpoints.IrredZone`
+.. |KpointStar| replace:: :class:`abipy.core.kpoints.KpointStar`
+.. |Structure| replace:: :class:`abipy.core.structure.Structure`
+.. |pymatgen-Structure| replace:: :class:`pymatgen.core.structure.Structure`
+.. |Lattice| replace:: :class:`pymatgen.core.lattice.Lattice`
+.. |AbinitInput| replace:: :class:`abipy.abio.inputs.AbinitInput`
+.. |MultiDataset| replace:: :class:`abipy.abio.inputs.MultiDataset`
+.. |ElectronBands| replace:: :class:`abipy.electrons.ebands.ElectronBands`
+.. |SkwInterpolator| replace:: :class:`abipy.core.skw.SkwInterpolator`
+.. |ElectronDos| replace:: :class:`abipy.electrons.ebands.ElectronDos`
+.. |PhononBands| replace:: :class:`abipy.dfpt.phonons.PhononBands`
+.. |Task| replace:: :class:`pymatgen.io.abinit.tasks.Task`
+.. |ScfTask| replace:: :class:`pymatgen.io.abinit.tasks.ScfTask`
+.. |NscfTask| replace:: :class:`pymatgen.io.abinit.tasks.NscfTask`
+.. |Flow| replace:: :class:`pymatgen.io.abinit.flows.Flow`
+.. |Work| replace:: :class:`pymatgen.io.abinit.works.Work`
+.. |TaskManager| replace:: :class:`pymatgen.io.abinit.tasks.TaskManager`
+.. |GsrFile| replace:: :class:`abipy.electrons.gsr.GsrFile`
+.. |GsrRobot| replace:: :class:`abipy.electrons.gsr.GsrRobot`
+.. |DdbFile| replace:: :class:`abipy.dfpt.ddb.DdbFile`
+.. |DdbRobot| replace:: :class:`abipy.dfpt.ddb.DdbRobot`
+.. |PhbstFile| replace:: :class:`abipy.dfpt.phonons.PhbstFile`
+.. |PhdosFile| replace:: :class:`abipy.dfpt.phonons.PhdosFile`
+.. |PhononDos| replace:: :class:`abipy.dfpt.phonons.PhononDos`
+.. |PhononBandsPlotter| replace:: :class:`abipy.dfpt.phonons.PhononBandsPlotter`
+.. |PhononDosPlotter| replace:: :class:`abipy.dfpt.phonons.PhononDosPlotter`
+.. |Pseudo| replace:: :class:`pymatgen.io.abinit.pseudos.Pseudo`
+.. |PseudoTable| replace:: :class:`pymatgen.io.abinit.pseudos.PseudoTable`
+.. |Visualizer| replace:: :class:`abipy.iotools.visualizer.Visualizer`
+
+.. Important objects provided by libraries.
+.. |matplotlib-Figure| replace:: :class:`matplotlib.figure.Figure`
+.. |matplotlib-Axes| replace:: :class:`matplotlib.axes.Axes`
+.. |pandas-DataFrame| replace:: :class:`pandas.DataFrame`
+.. |pandas-DataFrames| replace:: :class:`pandas.DataFrame`
+.. |numpy-array| replace:: :class:`numpy.ndarray`