Docs finalized

loli · Feb 3, 2024 · 507f67e · 507f67e
1 parent 7dd5979
commit 507f67e
Show file tree

Hide file tree

Showing 19 changed files with 82 additions and 80 deletions.
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -0,0 +1 @@
+generated/
diff --git a/doc/README.md b/doc/README.md
@@ -1,50 +1,11 @@
 # Building the HTML documentation
 
-Install sphinx first in your environment. Make sure to have the right version.
+Install MedPy with the `[doc]` extras
 
-    pip3 install sphinx==1.6.7
+    pip3 install medpy[doc]
 
-and test if the right binary is called. Higher versions break with the used numpydoc version.
-
-Then run
+Then run in `docs/`
 
     sphinx-build -aE -b html source/ build/
 
-, then edit .rst files belong to Python classes
-
-source/generated/medpy.graphcut.graph.Graph.rst
-source/generated/medpy.graphcut.graph.GCGraph.rst
-source/generated/medpy.filter.IntensityRangeStandardization.IntensityRangeStandardization.rst
-source/generated/medpy.core.logger.Logger.rst
-source/generated/medpy.header.Header.rst
-source/generated/medpy.iterators.*
-
-by removing the line
-
-    .. automethod:: __init__
-
-and adding the line
-
-    :toctree: generated/
-
-beneath each ".. autosummary::" command.
-
-Finally rerun the build
-
-    sphinx-build -aE -b html source/ build/
-
-
-## Enabling the search box
-
-Remove
-
-    scipy-sphinx-theme/_theme/scipy/searchbox.html
-
-from the scipy template, as it somehow overrides the search box with a custom link to edit the .rst files in-place online.
-
-
-## Generate the API documentation files
-
-Run
-
-    sphinx-apidoc -efF -H MedPy -A "Oskar Maier" -V 0.2 -R 1 -o generated/ ../../medpy/medpy/
+You can now find the HTML files in the `build/` folder.
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -107,7 +107,7 @@
     "header_links_before_dropdown": 5,
     "show_prev_next": False,
     "navigation_with_keys": False,
-    "use_edit_page_button": True,
+    "use_edit_page_button": False,
     "github_url": "https://github.com/loli/medpy/",
     "navbar_center": ["navbar-nav"],
 }

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -1,3 +1,4 @@
+=====
 MedPy
 =====
 
@@ -10,60 +11,39 @@ Installation
 ------------
 
 .. toctree::
-    :maxdepth: 1
-
-    installation/fastpath
-    installation/venv
-    installation/developmentmode
-    installation/graphcutsupport
-    installation/windows
-    installation/osx
-    installation/conda
-    installation/python2
-    installation/uninstall
+  :maxdepth: 2
+
+  installation/index
 
 Information
 -----------
 
 .. toctree::
-    :glob:
-    :maxdepth: 1
+  :maxdepth: 2
 
-    information/*
+  information/index
 
 Tutorials
 ---------
 
 .. toctree::
-    :glob:
-    :maxdepth: 1
+  :maxdepth: 2
 
-    tutorial/*
+  tutorial/index
 
 Notebooks
 ---------
 
-`Accessing the image's meta-data <https://github.com/loli/medpy/blob/master/notebooks/Accessing%20the%20image's%20meta-data.ipynb>`_.
-  In this tutorial we will learn how to access and manipulate the image's meta-data form the header.
+.. toctree::
+  :maxdepth: 2
 
-`Load, threshold and save an image <https://github.com/loli/medpy/blob/master/notebooks/Load%2C%20threshold%20and%20save%20an%20image.ipynb>`_.
-  In this tutorial you will learn how to load a medical image with MedPy, how to perform a simple thresholding operation and how to save the resulting binary image.
+  notebooks/index
 
-`Simple binary image processing <https://github.com/loli/medpy/blob/master/notebooks/Simple%20binary%20image%20processing.ipynb>`_.
-  In this tutorial you will learn some simple binary image processing.
 
 Reference
 ---------
 
 .. toctree::
-    :maxdepth: 1
-
-    io
-    metric
-    filter
-    features
-    iterators
-    neighbours
-    graphcut
-    core
-    utilities
+  :maxdepth: 1
+
+  reference/index
diff --git a/doc/source/information/index.rst b/doc/source/information/index.rst
@@ -0,0 +1,9 @@
+===========
+Information
+===========
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    *
diff --git a/doc/source/installation/index.rst b/doc/source/installation/index.rst
@@ -0,0 +1,16 @@
+============
+Installation
+============
+
+.. toctree::
+    :maxdepth: 1
+
+    fastpath
+    venv
+    developmentmode
+    graphcutsupport
+    windows
+    osx
+    conda
+    python2
+    uninstall
diff --git a/doc/source/notebooks/index.rst b/doc/source/notebooks/index.rst
@@ -0,0 +1,12 @@
+=========
+Notebooks
+=========
+
+`Accessing the image's meta-data <https://github.com/loli/medpy/blob/master/notebooks/Accessing%20the%20image's%20meta-data.ipynb>`_.
+  In this tutorial we will learn how to access and manipulate the image's meta-data form the header.
+
+`Load, threshold and save an image <https://github.com/loli/medpy/blob/master/notebooks/Load%2C%20threshold%20and%20save%20an%20image.ipynb>`_.
+  In this tutorial you will learn how to load a medical image with MedPy, how to perform a simple thresholding operation and how to save the resulting binary image.
+
+`Simple binary image processing <https://github.com/loli/medpy/blob/master/notebooks/Simple%20binary%20image%20processing.ipynb>`_.
+  In this tutorial you will learn some simple binary image processing.
diff --git a/doc/source/core.rst → doc/source/reference/core.rst b/doc/source/core.rst → doc/source/reference/core.rst
diff --git a/doc/source/features.rst → doc/source/reference/features.rst b/doc/source/features.rst → doc/source/reference/features.rst
diff --git a/doc/source/filter.rst → doc/source/reference/filter.rst b/doc/source/filter.rst → doc/source/reference/filter.rst
diff --git a/doc/source/graphcut.rst → doc/source/reference/graphcut.rst b/doc/source/graphcut.rst → doc/source/reference/graphcut.rst
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
@@ -0,0 +1,16 @@
+=========
+Reference
+=========
+
+.. toctree::
+    :maxdepth: 1
+
+    io
+    metric
+    filter
+    features
+    iterators
+    neighbours
+    graphcut
+    core
+    utilities
diff --git a/doc/source/io.rst → doc/source/reference/io.rst b/doc/source/io.rst → doc/source/reference/io.rst
diff --git a/doc/source/iterators.rst → doc/source/reference/iterators.rst b/doc/source/iterators.rst → doc/source/reference/iterators.rst
diff --git a/doc/source/metric.rst → doc/source/reference/metric.rst b/doc/source/metric.rst → doc/source/reference/metric.rst
diff --git a/doc/source/neighbours.rst → doc/source/reference/neighbours.rst b/doc/source/neighbours.rst → doc/source/reference/neighbours.rst
diff --git a/doc/source/utilities.rst → doc/source/reference/utilities.rst b/doc/source/utilities.rst → doc/source/reference/utilities.rst
diff --git a/doc/source/tutorial/index.rst b/doc/source/tutorial/index.rst
@@ -0,0 +1,9 @@
+========
+Tutorial
+========
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    *
diff --git a/setup.py b/setup.py
@@ -177,8 +177,6 @@ def run_setup(with_compilation):
                 "sphinx >= 1.6",
                 "numpydoc",
                 "pydata-sphinx-theme",
-                # "sphinx-panels",
-                # "sphinx-tabs",
             ],  # for documentation generation
         },
         packages=PACKAGES + ap,