Added main page, full API reference and license banner

ptycho · Dec 18, 2024 · 3f6d61f · 3f6d61f
1 parent d0a455a
commit 3f6d61f
Show file tree

Hide file tree

Showing 22 changed files with 633 additions and 183 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -72,7 +72,7 @@ jobs:
           mpi: mpich
 
       - name: Install Sphinx
-        run: pip install sphinx
+        run: pip install sphinx myst_parser
 
       - name: Install PtyPy
         run: pip install .[full]

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+source/reference/generated/
+_build/
diff --git a/docs/Makefile b/docs/Makefile
@@ -5,7 +5,7 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
+SOURCEDIR     = source
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".

diff --git a/docs/conf.py b/docs/conf.py
diff --git a/docs/index.rst b/docs/index.rst
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
diff --git a/docs/reference/utils.rst b/docs/reference/utils.rst
diff --git a/docs/source/_static/banner.html b/docs/source/_static/banner.html
@@ -0,0 +1,14 @@
+<div class="community-message">
+PtyPy is a community project. If you'd like to contribute or participate in one of our workshops, <a class='reference external' href='https://ptypy.org'>check out our website</a>.
+</div>
+<div id="disclaimer">
+<div class="disclaimer">
+<hr style="border: 1;">
+<p> Phase Focus Limited of Sheffield, UK has an international portfolio of patents and pending applications which relate to ptychography.  A current list is available <a class="reference external" href="http://www.phasefocus.com/patents/">here</a>.</p><p> 
+Phase Focus grants royalty free licences of its patent rights for non-commercial academic research use, for reconstruction of simulated data and for reconstruction of data obtained at synchrotrons at X-ray wavelengths. These licenses can be applied for online by clicking on this <a class="reference external" href="http://www.phasefocus.com/licence/">link</a>.</p><p> 
+Phase Focus asserts that the software we have made available for download may be capable of being used in circumstances which may fall within the claims of one or more of the Phase Focus patents. Phase Focus advises that you apply for a licence from it before downloading any software from this website. </p>
+<button type="button"
+onclick="document.getElementById('disclaimer').innerHTML = ''">
+I understand</button>
+</div>
+</div>
diff --git a/docs/_static/logo_100px.png → docs/source/_static/logo_100px.png b/docs/_static/logo_100px.png → docs/source/_static/logo_100px.png
diff --git a/docs/source/_static/ptypy.css b/docs/source/_static/ptypy.css
@@ -0,0 +1,18 @@
+div.disclaimer {
+    /* background-color: #2c5d8a;
+    color: #f9eed0; */
+    text-align: left;
+}
+
+/* div.disclaimer a{
+    color: #d8b340;
+} */
+
+html[data-theme="light"] {
+    --pst-color-border: black;
+}
+
+html[data-theme="dark"] {
+    --pst-color-border: white;
+}
+
diff --git a/docs/_static/ptypyicon.ico → docs/source/_static/ptypyicon.ico b/docs/_static/ptypyicon.ico → docs/source/_static/ptypyicon.ico
diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst
@@ -0,0 +1,32 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_templates/custom-module-template.rst
@@ -0,0 +1,65 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}