Generate documentation (#52)

* include autodoc * autodoc earthspy * add autosummary * generated earthspy page * change html theme * add template * improve doc conf * fix version * remove matplotlib * remove plot_directive * remove doc references * remove example library
AdrienWehrle · May 2, 2022 · 795f8fe · 795f8fe
1 parent a33442b
commit 795f8fe
Show file tree

Hide file tree

Showing 15 changed files with 227 additions and 21 deletions.
diff --git a/docs/.#index.rst b/docs/.#index.rst
@@ -0,0 +1 @@
+[email protected]:1651272210
diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle
diff --git a/docs/_build/doctrees/index.doctree b/docs/_build/doctrees/index.doctree
diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 9c8b1c4a938c9dc4ec3bdad471a320c3
+config: b79dd4f55baf953d95ecd9bb9a9b0003
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/_build/html/_sources/index.rst.txt b/docs/_build/html/_sources/index.rst.txt
@@ -7,11 +7,11 @@ Welcome to earthspy's documentation!
 ====================================
 
 .. toctree::
+   api
    :maxdepth: 2
    :caption: Contents:
 
 
-
 Indices and tables
 ==================
 

diff --git a/docs/_build/html/genindex.html b/docs/_build/html/genindex.html
@@ -34,8 +34,36 @@
 <h1 id="index">Index</h1>
 
 <div class="genindex-jumpbox">
+ <a href="#E"><strong>E</strong></a>
+ | <a href="#M"><strong>M</strong></a>
 
 </div>
+<h2 id="E">E</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li>
+    earthspy
+
+      <ul>
+        <li><a href="generated/earthspy.html#module-earthspy">module</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
+<h2 id="M">M</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+  <td style="width: 33%; vertical-align: top;"><ul>
+      <li>
+    module
+
+      <ul>
+        <li><a href="generated/earthspy.html#module-earthspy">earthspy</a>
+</li>
+      </ul></li>
+  </ul></td>
+</tr></table>
+
 
 
           </div>
@@ -54,6 +82,10 @@ <h1 class="logo"><a href="index.html">earthspy</a></h1>
 
 
 <h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
+</ul>
 
 <div class="relations">
 <h3>Related Topics</h3>

diff --git a/docs/_build/html/index.html b/docs/_build/html/index.html
@@ -15,6 +15,7 @@
     <script src="_static/doctools.js"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="API" href="api.html" />
 
   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
 
@@ -34,6 +35,10 @@
   <section id="welcome-to-earthspy-s-documentation">
 <h1>Welcome to earthspy’s documentation!<a class="headerlink" href="#welcome-to-earthspy-s-documentation" title="Permalink to this headline">¶</a></h1>
 <div class="toctree-wrapper compound">
+<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
+</ul>
 </div>
 </section>
 <section id="indices-and-tables">
@@ -62,11 +67,16 @@ <h1 class="logo"><a href="#">earthspy</a></h1>
 
 
 <h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
+</ul>
 
 <div class="relations">
 <h3>Related Topics</h3>
 <ul>
   <li><a href="#">Documentation overview</a><ul>
+      <li>Next: <a href="api.html" title="next chapter">API</a></li>
   </ul></li>
 </ul>
 </div>

diff --git a/docs/_build/html/objects.inv b/docs/_build/html/objects.inv
diff --git a/docs/_build/html/search.html b/docs/_build/html/search.html
@@ -83,6 +83,10 @@ <h1 class="logo"><a href="index.html">earthspy</a></h1>
 
 
 <h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="api.html">API</a></li>
+</ul>
 
 <div class="relations">
 <h3>Related Topics</h3>

diff --git a/docs/_build/html/searchindex.js b/docs/_build/html/searchindex.js
diff --git a/docs/_templates/module.rst b/docs/_templates/module.rst
@@ -0,0 +1,67 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+
+   .. contents:: Contents
+      :local:
+
+   {% block functions %}
+   {% if functions %}
+
+   Functions
+   =========
+
+   {% for item in functions %}
+
+   {{item}}
+   {{ "-" * (item | length) }}
+
+   .. autofunction:: {{ item }}
+
+   .. _sphx_glr_backref_{{fullname}}.{{item}}:
+
+   .. minigallery:: {{fullname}}.{{item}}
+       :add-heading:
+
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+
+   Classes
+   =======
+
+   {% for item in classes %}
+
+   {{item}}
+   {{ "-" * (item | length) }}
+
+   .. autoclass:: {{ item }}
+      :show-inheritance:
+      :special-members: __init__
+      :members:
+
+   .. _sphx_glr_backref_{{fullname}}.{{item}}:
+
+   .. minigallery:: {{fullname}}.{{item}}
+       :add-heading:
+
+   {% endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+
+   Exceptions
+   ==========
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,17 @@
+API
+===
+
+.. currentmodule:: earthspy
+
+.. autosummary::
+   :toctree: generated/
+   :template: module.rst
+   :recursive:
+
+   earthspy
+
+
+.. automodule earthspy
+
+   .. contents:: Contents
+      :local:
diff --git a/docs/conf.py b/docs/conf.py
@@ -9,47 +9,99 @@
 # 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.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
 
+import os
+import sys
 
-# -- Project information -----------------------------------------------------
+# Allow conf.py to find the earthspy module
+sys.path.append(os.path.abspath("../"))
+sys.path.append(os.path.abspath("../earthspy/"))
 
-project = 'earthspy'
-copyright = '2022, Adrien Wehrlé'
-author = 'Adrien Wehrlé'
 
-# The full version, including alpha/beta/rc tags
-release = 'v0.1.0'
+# -- Project information -----------------------------------------------------
+
+project = "earthspy"
+copyright = "2022, Adrien Wehrlé"
+author = "Adrien Wehrlé"
 
+# Set the python environment variable for programoutput to find it.
+os.environ["PYTHON"] = sys.executable
 
 # -- General configuration ---------------------------------------------------
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '3.3.1'
+master_doc = "index"
+
 extensions = [
+    "sphinx.ext.autodoc",  # Create the API documentation automatically
+    "sphinx.ext.viewcode",  # Create the "[source]" button in the API to show the source code.
+    "sphinx.ext.autosummary",  # Create API doc summary texts from the docstrings.
+    "sphinx.ext.inheritance_diagram",  # For class inheritance diagrams (see coregistration.rst).
+    "sphinx_autodoc_typehints",  # Include type hints in the API documentation.
+    "sphinxcontrib.programoutput",
+    # "sphinx_gallery.gen_gallery",  # Examples gallery
+    "sphinx.ext.intersphinx",
 ]
 
+intersphinx_mapping = {
+    "rasterio": ("https://rasterio.readthedocs.io/en/latest", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+}
+
+sphinx_gallery_conf = {
+    # "examples_dirs": os.path.join(
+    #     os.path.dirname(__file__), "../", "../", "examples"
+    # ),  # path to your example scripts
+    # "gallery_dirs": "auto_examples",  # path to where to save gallery generated output
+    # "inspect_global_variables": True,  # Make links to the class/function definitions.
+    "reference_url": {
+        # The module you locally document uses None
+        "earthspy": None,
+    },
+    "filename_pattern": r".*\.py",  # Run all python files in the gallery (by default, only files starting with "plot_" are run)
+    # directory where function/class granular galleries are stored
+    # "backreferences_dir": "gen_modules/backreferences",
+    "doc_module": (
+        "earthspy"
+    ),  # which function/class levels are used to create galleries
+}
+
+extlinks = {
+    "issue": ("https://github.com/AdrienWehrle/earthspy/issues/%s", "GH"),
+    "pull": ("https://github.com/AdrienWehrle/earthspy/pull/%s", "PR"),
+}
+
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = [os.path.join(os.path.dirname(__file__), "_templates")]
+
+import earthspy
+
+# The short X.Y version
+version = "v0.1"
+# The full version, including alpha/beta/rc tags.
+release = "v0.1.0"
+
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "_templates"]
 
+# autodoc_default_options = {
+#        "special-members": "__init__",
+# }
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
+
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
diff --git a/docs/generated/earthspy.rst b/docs/generated/earthspy.rst
@@ -0,0 +1,23 @@
+earthspy
+========
+
+.. automodule:: earthspy
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -7,11 +7,11 @@ Welcome to earthspy's documentation!
 ====================================
 
 .. toctree::
+   api
    :maxdepth: 2
    :caption: Contents:
 
 
-
 Indices and tables
 ==================