Clean up python documentation by fixing the warnings from the stub pa…

…rser (#1917) * move as_f64 to PropUnwrap trait so we can directly apply it to e.g. Option<Prop> * tidy up pyvis export * start fixing the doc strings * more updates * autogenerating docs * upgrade dependencies * tidy up conf and add workaround for linking to type alias * tidy up the docs * add subheading to type alias page * add the fallback to type for all class references instead of having to manually specify them * we haven't used the rust docs being build on readthedocs for a while, no need to keep building them * tidy * get the external links working * update pyvis tests for new defaults * fix some minor documentation issues * hide the pickle internals
Pometry · Jan 17, 2025 · 06b6d48 · 06b6d48
1 parent e4663e3
commit 06b6d48
Show file tree

Hide file tree

Showing 78 changed files with 3,027 additions and 1,425 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -13,12 +13,11 @@ build:
   jobs:
     pre_build:
       - curl https://sh.rustup.rs -sSf | sh -s -- -y
-      - PATH=$HOME/.cargo/bin:$PATH make rust-build-readthedocs
       - PATH=$HOME/.cargo/bin:$PATH make install-python
 
 conda:
   environment: .environment.yml
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/source/conf.py
+  configuration: docs/source/conf.py
diff --git a/docs/requirements.in b/docs/requirements.in
@@ -4,6 +4,6 @@ sphinx_copybutton
 sphinx_design
 sphinx_favicon
 autodocsumm
-nbsphinx
 numpydoc
-pydata-sphinx-theme
+pydata-sphinx-theme
+sphinx >= 8
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,127 +1,58 @@
 #
-# This file is autogenerated by pip-compile with Python 3.11
+# This file is autogenerated by pip-compile with Python 3.12
 # by the following command:
 #
 #    pip-compile requirements.in
 #
 accessible-pygments==0.0.5
     # via pydata-sphinx-theme
-alabaster==0.7.16
+alabaster==1.0.0
     # via sphinx
-attrs==23.2.0
-    # via
-    #   jsonschema
-    #   referencing
-autodocsumm==0.2.12
+autodocsumm==0.2.14
     # via -r requirements.in
-babel==2.15.0
+babel==2.16.0
     # via
     #   pydata-sphinx-theme
     #   sphinx
 beautifulsoup4==4.12.3
-    # via
-    #   nbconvert
-    #   pydata-sphinx-theme
-bleach==6.1.0
-    # via nbconvert
-certifi==2024.7.4
+    # via pydata-sphinx-theme
+certifi==2024.12.14
     # via requests
-charset-normalizer==3.3.2
+charset-normalizer==3.4.1
     # via requests
-defusedxml==0.7.1
-    # via nbconvert
 docutils==0.21.2
     # via
-    #   nbsphinx
     #   pydata-sphinx-theme
     #   sphinx
-fastjsonschema==2.19.1
-    # via nbformat
-idna==3.7
+idna==3.10
     # via requests
 imagesize==1.4.1
     # via sphinx
 jinja2==3.1.5
-    # via
-    #   nbconvert
-    #   nbsphinx
-    #   sphinx
-jsonschema==4.22.0
-    # via nbformat
-jsonschema-specifications==2023.12.1
-    # via jsonschema
-jupyter-client==8.6.2
-    # via nbclient
-jupyter-core==5.7.2
-    # via
-    #   jupyter-client
-    #   nbclient
-    #   nbconvert
-    #   nbformat
-jupyterlab-pygments==0.3.0
-    # via nbconvert
-markupsafe==2.1.5
-    # via
-    #   jinja2
-    #   nbconvert
-mistune==3.0.2
-    # via nbconvert
-nbclient==0.10.0
-    # via nbconvert
-nbconvert==7.16.4
-    # via nbsphinx
-nbformat==5.10.4
-    # via
-    #   nbclient
-    #   nbconvert
-    #   nbsphinx
-nbsphinx==0.9.4
-    # via -r requirements.in
-numpydoc==1.7.0
+    # via sphinx
+markupsafe==3.0.2
+    # via jinja2
+numpydoc==1.8.0
     # via -r requirements.in
-packaging==24.1
-    # via
-    #   nbconvert
-    #   pydata-sphinx-theme
-    #   sphinx
-pandocfilters==1.5.1
-    # via nbconvert
-platformdirs==4.2.2
-    # via jupyter-core
-pydata-sphinx-theme==0.15.3
+packaging==24.2
+    # via sphinx
+pydata-sphinx-theme==0.16.1
     # via -r requirements.in
-pygments==2.18.0
+pygments==2.19.1
     # via
     #   accessible-pygments
-    #   nbconvert
     #   pydata-sphinx-theme
     #   sphinx
-python-dateutil==2.9.0.post0
-    # via jupyter-client
-pyzmq==26.0.3
-    # via jupyter-client
-referencing==0.35.1
-    # via
-    #   jsonschema
-    #   jsonschema-specifications
 requests==2.32.3
     # via sphinx
-rpds-py==0.18.1
-    # via
-    #   jsonschema
-    #   referencing
-six==1.16.0
-    # via
-    #   bleach
-    #   python-dateutil
 snowballstemmer==2.2.0
     # via sphinx
-soupsieve==2.5
+soupsieve==2.6
     # via beautifulsoup4
-sphinx==7.3.7
+sphinx==8.1.3
     # via
+    #   -r requirements.in
     #   autodocsumm
-    #   nbsphinx
     #   numpydoc
     #   pydata-sphinx-theme
     #   sphinx-autosummary-accessors
@@ -133,43 +64,27 @@ sphinx-autosummary-accessors==2023.4.0
     # via -r requirements.in
 sphinx-copybutton==0.5.2
     # via -r requirements.in
-sphinx-design==0.6.0
+sphinx-design==0.6.1
     # via -r requirements.in
 sphinx-favicon==1.0.1
     # via -r requirements.in
-sphinx-notfound-page==1.0.2
+sphinx-notfound-page==1.0.4
     # via -r requirements.in
-sphinxcontrib-applehelp==1.0.8
+sphinxcontrib-applehelp==2.0.0
     # via sphinx
-sphinxcontrib-devhelp==1.0.6
+sphinxcontrib-devhelp==2.0.0
     # via sphinx
-sphinxcontrib-htmlhelp==2.0.5
+sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
-sphinxcontrib-qthelp==1.0.7
+sphinxcontrib-qthelp==2.0.0
     # via sphinx
-sphinxcontrib-serializinghtml==1.1.10
+sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 tabulate==0.9.0
     # via numpydoc
-tinycss2==1.3.0
-    # via nbconvert
-tornado==6.4.2
-    # via jupyter-client
-traitlets==5.14.3
-    # via
-    #   jupyter-client
-    #   jupyter-core
-    #   nbclient
-    #   nbconvert
-    #   nbformat
-    #   nbsphinx
 typing-extensions==4.12.2
     # via pydata-sphinx-theme
-urllib3==2.2.2
+urllib3==2.3.0
     # via requests
-webencodings==0.5.1
-    # via
-    #   bleach
-    #   tinycss2
diff --git a/docs/source/404.rst b/docs/source/404.rst
@@ -1,5 +1,4 @@
 :orphan:
-.. _notfound:
 
 Page Not Found
 ==============

diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
@@ -3,7 +3,7 @@
 }
 
 .search-button__kbd-shortcut {
-  display: none !important;
+    display: none !important;
 }
 
 .theme-switch-button {
@@ -25,13 +25,109 @@
 
 /* Change the text color of the navbar links */
 .navbar a {
-  color: #ffffff !important;
+    color: #ffffff !important;
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 400;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Regular Italic.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 400;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Regular.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 250;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Thin Italic.woff') format('woff')
 }
 
-@font-face{font-family:proxima nova;font-style:normal;font-weight:400;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Regular Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:400;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Regular.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:250;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Thin Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:250;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Thin.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:300;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Light.woff') format('woff')}@font-face{font-family:proxima nova;font-style:italic;font-weight:300;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Light Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:600;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Semibold Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:600;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Semibold.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:700;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Bold Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:700;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Bold.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:800;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Extrabold Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:800;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Extrabold.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:900;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Black Italic.woff') format('woff')}@font-face{font-family:proxima nova;font-style:normal;font-weight:900;src:local('Proxima Nova'),url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Black.woff') format('woff')}
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 250;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Thin.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 300;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Light.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: italic;
+    font-weight: 300;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Light Italic.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 600;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Semibold Italic.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 600;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Semibold.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 700;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Bold Italic.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 700;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Bold.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 800;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Extrabold Italic.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 800;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Extrabold.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 900;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Black Italic.woff') format('woff')
+}
+
+@font-face {
+    font-family: proxima nova;
+    font-style: normal;
+    font-weight: 900;
+    src: local('Proxima Nova'), url('https://fonts.cdnfonts.com/s/27118/Mark Simonson  Proxima Nova Black.woff') format('woff')
+}
 
 html {
     --pst-font-family-base: 'proxima nova', var(--pst-font-family-base-system);
     --pst-font-family-heading: 'proxima nova', Georgia, Times, var(--pst-font-family-base-system);
     --pst-font-family-monospace: 'proxima nova', var(--pst-font-family-monospace-system);
-}
+}
diff --git a/docs/source/_templates/autosummary/base.rst b/docs/source/_templates/autosummary/base.rst
@@ -0,0 +1,5 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}
diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst
@@ -0,0 +1,9 @@
+{{ name | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :autosummary:
+   :members:
+   :undoc-members:
+   :show-inheritance: