refactor docs tocs and index page (#239)

- puts the "tutorials" and "case studies" tocs under the "user's guide" toc, instead of them being their own TOCs. - breaks the API page out to its own TOC - moves the "citations" and "contributions" pages into their own .txt files for no good reason
scikit-tda · Oct 11, 2021 · f34945a · f34945a
1 parent aee3500
commit f34945a
Show file tree

Hide file tree

Showing 6 changed files with 128 additions and 98 deletions.
diff --git a/docs/case_studies.rst b/docs/case_studies.rst
@@ -0,0 +1,12 @@
+Case studies
+============
+
+These pages are in-depth applications of KeplerMapper to various interesting domains.
+
+.. toctree::
+    :maxdepth: 1
+
+    notebooks/KeplerMapper-Newsgroup20-Pipeline
+    notebooks/TOR-XGB-TDA
+    notebooks/Confidence-Graphs
+    notebooks/self-guessing
diff --git a/docs/citations.txt b/docs/citations.txt
@@ -0,0 +1,55 @@
+Citations
+---------
+
+To credit KeplerMapper in your work, please cite both the `JOSS paper`_
+and the `Zenodo archive`_. The former provides a high level description
+of the package, and the latter points to a permanent record of all KeplerMapper versions
+(we encourage you to cite the specific version you used).
+
+.. _JOSS paper: https://doi.org/10.21105/joss.01315
+.. _Zenodo archive: https://doi.org/10.5281/zenodo.1002377
+
+Example citations (for KeplerMapper 1.4.1):
+
+    van Veen et al., (2019). Kepler Mapper: A flexible Python implementation of the Mapper algorithm.
+    Journal of Open Source Software, 4(42), 1315, https://doi.org/10.21105/joss.01315
+
+    Hendrik Jacob van Veen, Nathaniel Saul, David Eargle, & Sam W. Mangham.
+    (2019, October 14). Kepler Mapper: A flexible Python implementation of the Mapper algorithm (Version 1.4.1).
+    Zenodo. http://doi.org/10.5281/zenodo.4077395
+
+Bibtex entry for JOSS article:
+
+::
+
+  @article{KeplerMapper_JOSS,
+      doi           = {10.21105/joss.01315},
+      url           = {https://doi.org/10.21105/joss.01315},
+      year          = {2019},
+      publisher     = {The Open Journal},
+      volume        = {4},
+      number        = {42},
+      pages         = {1315},
+      author        = {Hendrik Jacob van Veen and Nathaniel Saul and David Eargle and Sam W. Mangham},
+      title         = {Kepler Mapper: A flexible Python implementation of the Mapper algorithm.},
+      journal       = {Journal of Open Source Software}
+      }
+
+Bibtex entry for the Zenodo archive, version 1.4.1:
+
+::
+
+    @software{KeplerMapper_v1.4.1-Zenodo,
+        author       = {Hendrik Jacob van Veen and
+                        Nathaniel Saul and
+                        Eargle, David and
+                        Sam W. Mangham},
+        title        = {{Kepler Mapper: A flexible Python implementation of
+                         the Mapper algorithm}},
+        month        = oct,
+        year         = 2020,
+        publisher    = {Zenodo},
+        version      = {1.4.1},
+        doi          = {10.5281/zenodo.4077395},
+        url          = {https://doi.org/10.5281/zenodo.4077395}
+    }
diff --git a/docs/contributions.txt b/docs/contributions.txt
@@ -0,0 +1,12 @@
+Contributions
+-------------
+
+We welcome contributions of all shapes and sizes. There are lots of
+opportunities for potential projects, so please get in touch if you would like
+to help out. Everything from an implementation of your favorite distance,
+notebooks, examples, and documentation are all equally valuable so please don’t
+feel you can’t contribute.
+
+See `the contributing page in the code repository`__ for more details.
+
+__ https://github.com/scikit-tda/kepler-mapper/blob/master/CONTRIBUTING.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -7,124 +7,63 @@
 |Codecov| |DOI zenodo| |DOI JOSS|
 
 Kepler Mapper
-----------------
+=============
 
+.. epigraph::
 
-    Nature uses as little as possible of anything. - Johannes Kepler
+    Nature uses as little as possible of anything.
 
-This is a library implementing the Mapper algorithm in Python. KeplerMapper can be used for visualization of high-dimensional data and 3D point cloud data. KeplerMapper can make use of Scikit-Learn API compatible cluster and scaling algorithms. You can find the source code on github at
-`scikit-tda/kepler-mapper <https://github.com/scikit-tda/kepler-mapper>`_.
+    -- Johannes Kepler
 
-KeplerMapper employs approaches based on the MAPPER algorithm (Singh et al.) as first described in the paper "Topological Methods for the Analysis of High Dimensional Data Sets and 3D Object Recognition".
+This is a library implementing the Mapper algorithm in Python. KeplerMapper can
+be used for visualization of high-dimensional data and 3D point cloud data.
+KeplerMapper can make use of Scikit-Learn API compatible cluster and scaling
+algorithms. You can find the source code on github at
+`scikit-tda/kepler-mapper`_.
 
-Setup
-=======================
+.. _scikit-tda/kepler-mapper: https://github.com/scikit-tda/kepler-mapper
 
-Install KeplerMapper with pip:
+KeplerMapper employs approaches based on the MAPPER algorithm (Singh et al.) as
+first described in the paper "Topological Methods for the Analysis of High
+Dimensional Data Sets and 3D Object Recognition".
 
-::
 
-    pip install kmapper
+.. User's Guide
+.. ------------
+..
+.. These pages explain what KeplerMapper is, illustrate how to use it, and discuss
+.. and demonstrate applications of it.
 
 
 
-Citations
-=======================
-
-To credit KeplerMapper in your work, please cite both the `JOSS paper`_
-and the `Zenodo archive`_. The former provides a high level description
-of the package, and the latter points to a permanent record of all KeplerMapper versions
-(we encourage you to cite the specific version you used).
-
-.. _JOSS paper: https://doi.org/10.21105/joss.01315
-.. _Zenodo archive: https://doi.org/10.5281/zenodo.1002377
-
-Example citations (for KeplerMapper 1.4.1):
-
-    van Veen et al., (2019). Kepler Mapper: A flexible Python implementation of the Mapper algorithm.
-    Journal of Open Source Software, 4(42), 1315, https://doi.org/10.21105/joss.01315
-
-    Hendrik Jacob van Veen, Nathaniel Saul, David Eargle, & Sam W. Mangham.
-    (2019, October 14). Kepler Mapper: A flexible Python implementation of the Mapper algorithm (Version 1.4.1).
-    Zenodo. http://doi.org/10.5281/zenodo.4077395
-
-Bibtex entry for JOSS article:
-
-::
-
-  @article{KeplerMapper_JOSS,
-      doi           = {10.21105/joss.01315},
-      url           = {https://doi.org/10.21105/joss.01315},
-      year          = {2019},
-      publisher     = {The Open Journal},
-      volume        = {4},
-      number        = {42},
-      pages         = {1315},
-      author        = {Hendrik Jacob van Veen and Nathaniel Saul and David Eargle and Sam W. Mangham},
-      title         = {Kepler Mapper: A flexible Python implementation of the Mapper algorithm.},
-      journal       = {Journal of Open Source Software}
-      }
-
-Bibtex entry for the Zenodo archive, version 1.4.1:
-
-::
-
-    @software{KeplerMapper_v1.4.1-Zenodo,
-        author       = {Hendrik Jacob van Veen and
-                        Nathaniel Saul and
-                        Eargle, David and
-                        Sam W. Mangham},
-        title        = {{Kepler Mapper: A flexible Python implementation of
-                         the Mapper algorithm}},
-        month        = oct,
-        year         = 2020,
-        publisher    = {Zenodo},
-        version      = {1.4.1},
-        doi          = {10.5281/zenodo.4077395},
-        url          = {https://doi.org/10.5281/zenodo.4077395}
-    }
-
-
-
-Contributions
-=======================
-
-We welcome contributions of all shapes and sizes. There are lots of opportunities for potential projects, so please get in touch if you would like to help out. Everything from an implementation of your favorite distance, notebooks, examples, and documentation are all equally valuable so please don’t feel you can’t contribute.
-
-To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged into the main branch.
-
-.. include:: ../README.rst
 
 .. toctree::
-    :hidden:
-    :maxdepth: 1
-    :caption: User Guide
+    :caption: User's Guide
+    :maxdepth: 2
 
     theory
     started
     examples
     applications
-    reference/index
+    tutorials
+    case_studies
 
-.. toctree::
-    :hidden:
-    :maxdepth: 1
-    :caption: Tutorials
 
-    notebooks/Adapters
-    notebooks/Plotly-Demo
-    notebooks/Cancer-demo
-    notebooks/KeplerMapper-usage-in-Jupyter-Notebook
+.. API Reference
+.. -------------
+..
+.. These pages link to documentation for specific KeplerMapper classes and functions.
 
 .. toctree::
-    :hidden:
-    :maxdepth: 1
-    :caption: Advanced Case Studies
-
-    notebooks/KeplerMapper-Newsgroup20-Pipeline
-    notebooks/TOR-XGB-TDA
-    notebooks/Confidence-Graphs
-    notebooks/self-guessing
+    :caption: API Reference
+    :maxdepth: 2
+
+    reference/index
+
+
+.. include:: citations.txt
+.. include:: contributions.txt
+
 
 
 .. |Downloads| image:: https://img.shields.io/pypi/dm/kmapper

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -1,6 +1,6 @@
 
-API Reference
----------------
+API
+---
 
 .. currentmodule:: kmapper
 

diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -0,0 +1,12 @@
+Tutorials
+---------
+
+These pages demonstrate using KeplerMapper in various ways.
+
+.. toctree::
+    :maxdepth: 1
+
+    Visualization Adapters <notebooks/Adapters>
+    notebooks/Plotly-Demo
+    Choosing a Lens <notebooks/Cancer-demo>
+    notebooks/KeplerMapper-usage-in-Jupyter-Notebook