Rework API docs

.gitignore

@@ -57,7 +57,7 @@ cover/
 
 # Sphinx documentation
 docs/_build/
-docs/generated
+docs/ref/generated
 
 # PyBuilder
 .pybuilder/

docs/_static/css/lentil.css

@@ -31,15 +31,12 @@ a:hover code{
     text-decoration-thickness: 1px;
 }
 
-.sig-name {
-    --pst-color-inline-code: #5E81AC;
+a.headerlink {
+    color: #ee9040;
 }
 
-pre {
-    background-color: #f8f8f8;
-    border: 0px;
-    box-shadow: none;
-    padding: 20px;
+.sig-name {
+    --pst-color-inline-code: #5E81AC;
 }
 
 h1, h2, h3, h4, h5, h6 {
@@ -89,6 +86,11 @@ a.hederlink:hover {
     color: #ee9040
 }
 
+/* Disable API reference name highlighting */
+dt:target, span.highlighted {
+    background-color: transparent;
+}
+
 :target:before{
     content:"";
     display:block;

docs/_templates/autosummary/attribute.rst

@@ -0,0 +1,7 @@
+:orphan:
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ fullname | replace("lentil.", "lentil::") }}

docs/_templates/autosummary/class.rst

@@ -1,26 +1,31 @@
-{% extends "!autosummary/class.rst" %}
+{{ fullname | escape | underline}}
 
-{% block methods %}
-{% if methods %}
-   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
-      .. autosummary::
-         :toctree:
-      {% for item in all_methods %}
-         {%- if not item.startswith('_') or item in ['__call__'] %}
-         {{ name }}.{{ item }}
-         {%- endif -%}
-      {%- endfor %}
-{% endif %}
-{% endblock %}
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
 
-{% block attributes %}
 {% if attributes %}
-   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
-      .. autosummary::
-      {% for item in all_attributes %}
-         {%- if not item.startswith('_') %}
-         {{ name }}.{{ item }}
-         {%- endif -%}
-      {%- endfor %}
+.. rubric:: {{ _('Attributes') }}
+
+.. autosummary::
+    :toctree:
+    {% for item in attributes %}
+    {%- if not item.startswith('_') %}
+    ~{{ name }}.{{ item }}
+    {%- endif -%}
+    {%- endfor %}
+
 {% endif %}
-{% endblock %}
+
+{% if methods %}
+.. rubric:: {{ _('Methods') }}
+
+.. autosummary::
+    :toctree:
+    {% for item in methods %}
+    {%- if not item.startswith('_') or item in ['__call__'] %}
+    ~{{ name }}.{{ item }}
+    {%- endif -%}
+    {%- endfor %}
+
+{% endif %}

docs/_templates/autosummary/property.rst

@@ -0,0 +1,12 @@
+:orphan:
+
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoattribute:: {{ fullname | replace("lentil.", "lentil::") }}
+
+{# Normally this line would read
+    .. auto{{ objtype }}:: {{ fullname | replace("lentil.", "lentil::") }}
+but we've explicitly called autoattribute so that properties are rendered
+in a way that is indistinguishable from attributes #}

docs/_templates/index.html

@@ -63,7 +63,7 @@ <h1>Lentil: Fast optical propagation</h1>
             </div>
 
             <div class="col-3">
-                <a href="{{ pathto("reference") }}">
+                <a href="{{ pathto("ref/index") }}">
                     <img src="_static/reference.svg"><br/>
                     Reference
                 </a>

docs/conf.py

@@ -21,6 +21,7 @@
 with open(os.path.normpath(os.path.join(path, '..', 'lentil', '__init__.py'))) as f:
     version = release = re.search("__version__ = '(.*?)'", f.read()).group(1)
 
+today_fmt = '%B %d, %Y'
 
 # -- General configuration ---------------------------------------------------
 
@@ -32,8 +33,8 @@
               'sphinx_remove_toctrees',
               'sphinx_copybutton',
               'sphinx_design',
-              'matplotlib.sphinxext.plot_directive',
-              'numpydoc']
+              'matplotlib.sphinxext.plot_directive']#,
+              #'numpydoc']
 templates_path = ['_templates']
 source_suffix = '.rst'
 master_doc = 'docs'
@@ -53,6 +54,8 @@
    },
    "collapse_navigation": True,
    "navbar_persistent": ["search-button"],
+   "pygment_light_style": "tango",
+   "pygment_dark_style": "nord",
    "favicons": [
       {
          "rel": "icon",
@@ -93,20 +96,20 @@
 
 html_css_files = ['css/lentil.css']
 
-pygments_style = 'default'
-
 # if true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 add_module_names = True
 
+add_function_parentheses = True
+
 autodoc_default_options = {
-    'member-order': 'bysource',
-    'undoc-members': None
-#    'exclude-members': '__init__, __weakref__, __dict__, __module__'
+    'member-order': 'alphabetical',
+    'exclude-members': '__init__, __weakref__, __dict__, __module__',
 }
 
 autosummary_generate = True
 
+
 #remove_from_toctrees = ["generated/*"]
 
 # -- Plot config -------------------------------------------------------------
@@ -138,16 +141,9 @@
 plot_html_show_formats = False
 plot_formats = [('png', dpi*2)]
 plot_pre_code = """
+import lentil
+import matplotlib.pyplot as plt
 import numpy as np
 np.random.seed(12345)
 """
 
-
-
-
-#def fix_attributes(app, pagename, templatename, context, doctree):
-#   if 'generated' in pagename:
-#      context['body'] = context['body'].replace('Variables', 'Attributes')
-
-#def setup(app):
-#     app.connect("html-page-context", fix_attributes)