Develop

README.md

@@ -11,31 +11,22 @@
 
 # tda-mapper
 
-**tda-mapper** is a simple and efficient Python library implementing the Mapper algorithm for Topological Data Analysis (TDA).
-It enables fast computation of Mapper graphs using *vp-trees* to optimize the construction of open covers for enhanced performance and scalability.
+**tda-mapper** is a simple and efficient Python library implementing the
+Mapper algorithm for Topological Data Analysis (TDA).
+It enables fast computation of Mapper graphs by using *vp-trees* to optimize
+the construction of open covers, improving both performance and scalability.
 
-For further details, please refer to our [preprint](https://doi.org/10.5281/zenodo.10659651).
-
-- **Installation**: `pip install tda-mapper`
-
-- **Documentation**: [Online on Read the Docs](https://tda-mapper.readthedocs.io/en/main/).
-
-- **Interactive App**: [Live Demo on Streamlit Cloud](https://tda-mapper-app.streamlit.app/), or run locally with:
-
-    ```
-    pip install -r app/requirements.txt
-    streamlit run app/streamlit_app.py
-    ```
-
-## Features
+For further details, please refer to the
+[preprint](https://doi.org/10.5281/zenodo.10659651) and 
+[online documentation](https://tda-mapper.readthedocs.io/en/main/).
 
 - **Efficient Mapper Computation**: Optimized for higher-dimensional lenses.
 
 - **Interactive Visualizations**: Multiple plotting backends for flexibility.
 
 - **Interactive App**: Interactive tool for quick, in-depth data exploration.
 
-## Background
+### Background
 
 The Mapper algorithm is a well-known technique in the field of topological
 data analysis that allows data to be represented as a graph.
@@ -52,9 +43,31 @@ read
 | ![Step 1](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_1.png) | ![Step 2](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_2.png) | ![Step 3](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_3.png) | ![Step 2](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_4.png) |
 | Chose lens | Cover image | Run clustering | Build graph |
 
+### Citations
+
+If you use **tda-mapper** in your work, please consider citing both the
+[library](https://doi.org/10.5281/zenodo.10642381), archived in a permanent
+Zenodo record, and the [preprint](https://doi.org/10.5281/zenodo.10659651),
+which provides a broader methodological overview.
+We recommend citing the specific version of the library used in your research,
+as well as the latest version of the preprint.
+For citation examples, refer to the
+[documentation](https://tda-mapper.readthedocs.io/en/main/citations.html).
+
 ## Quick Start
 
-Here's a minimal example using the **circles dataset** from `scikit-learn` to demonstrate how to use **tda-mapper**:
+### Installation
+
+To install the latest version uploaded on PyPI
+
+```bash
+pip install tda-mapper
+```
+
+### How to Use
+
+Here's a minimal example using the **circles dataset** from `scikit-learn` to
+demonstrate how to use **tda-mapper**:
 
 ```python
 import numpy as np
@@ -85,36 +98,15 @@ fig.show(config={'scrollZoom': True})
 | ![Original Dataset](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset.png) | ![Mapper Graph](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean.png) |
 
 More examples can be found in the
-[documentation](https://tda-mapper.readthedocs.io/en/main/).
-
-## Citations
-
-- **tda-mapper**: To cite this library, reference the Zenodo [archive](https://doi.org/10.5281/zenodo.10642381), pointing to the specific version of the release used in your work. For example to cite version 0.7.3 you can use:
-
-    ``` bibtex
-    @software{simi_2024_12729251,
-        author       = {Simi, Luca},
-        title        = {tda-mapper},
-        month        = jul,
-        year         = 2024,
-        publisher    = {Zenodo},
-        version      = {v0.7.3},
-        doi          = {10.5281/zenodo.12729251},
-        url          = {https://doi.org/10.5281/zenodo.12729251}
-    }
-    ```
-
-- **Methodology**: To cite our methodological foundation, refer to the [preprint](https://doi.org/10.5281/zenodo.10659651).
-
-    ``` bibtex
-    @misc{simi_2024_11187959,
-        author       = {Simi, Luca},
-        title        = {{A Scalable Approach for Mapper via Vantage Point 
-                        Trees}},
-        month        = may,
-        year         = 2024,
-        publisher    = {Zenodo},
-        doi          = {10.5281/zenodo.11187959},
-        url          = {https://doi.org/10.5281/zenodo.11187959}
-    }
-    ```
+[documentation](https://tda-mapper.readthedocs.io/en/main/examples.html).
+
+### Interactive App
+
+You can explore a live demo of **tda-mapper** directly on
+[Streamlit Cloud](https://tda-mapper-app.streamlit.app/),
+or run it locally using the following:
+
+```
+pip install -r app/requirements.txt
+streamlit run app/streamlit_app.py
+```

docs/source/conf.py

@@ -13,7 +13,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme', 'nbsphinx']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme', 'nbsphinx']
 
 templates_path = ['_templates']
 exclude_patterns = []
@@ -23,9 +23,15 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
 html_logo = 'logos/tda-mapper-logo-horizontal.png'
-
 html_theme_options = {
     'sticky_navigation': True,
+    'vcs_pageview_mode': 'blob',
+}
+html_context = {
+    'display_github': True,
+    'github_user': 'lucasimi',
+    'github_repo': 'tda-mapper-python',
+    'github_version': 'main',
+    'conf_py_path': '/docs/source/',
 }

docs/source/index.rst

@@ -30,29 +30,14 @@ tda-mapper
 ==========
 
 **tda-mapper** is a simple and efficient Python library implementing the
-Mapper algorithm for Topological Data Analysis (TDA). It enables fast
-computation of Mapper graphs using *vp-trees* to optimize the
-construction of open covers for enhanced performance and scalability.
+Mapper algorithm for Topological Data Analysis (TDA).
+It enables fast computation of Mapper graphs by using *vp-trees* to optimize
+the construction of open covers, improving both performance and scalability.
 
-For further details, please refer to our
-`preprint <https://doi.org/10.5281/zenodo.10659651>`__.
-
-- **Installation**: ``pip install tda-mapper``
-
-- **Documentation**:
-  `Online on Read the Docs <https://tda-mapper.readthedocs.io/en/main/>`__.
-
-- **Interactive App**:
-  `Live Demo on Streamlit Cloud <https://tda-mapper-app.streamlit.app/>`__,
-  or run Locally with:
-
-  ::
-
-      pip install -r app/requirements.txt
-      streamlit run app/streamlit_app.py
-
-Features
---------
+For further details, please refer to the
+`preprint <https://doi.org/10.5281/zenodo.10659651>`__,
+and 
+`online documentation <https://tda-mapper.readthedocs.io/en/main/>`__.
 
 - **Efficient Mapper Computation**: Optimized for higher-dimensional
   lenses.
@@ -63,6 +48,7 @@ Features
 - **Interactive App**: Interactive tool for quick, in-depth data
   exploration.
 
+
 Background
 ----------
 
@@ -83,10 +69,58 @@ paper <https://research.math.osu.edu/tgda/mapperPBG.pdf>`__.
 | Chose lens      | Cover image     | Run clustering  | Build graph     |
 +-----------------+-----------------+-----------------+-----------------+
 
+
+Citations
+---------
+
+If you use **tda-mapper** in your work, please consider citing both the 
+`library <https://doi.org/10.5281/zenodo.10642381>`__,
+archived in a permanent Zenodo record, and the 
+`preprint <https://doi.org/10.5281/zenodo.10659651>`__,
+which provides a broader methodological overview.
+We recommend citing the specific version of the library used in your research, as well as the latest version of the preprint.
+
+- **tda-mapper**: For example to cite version 0.7.3 you can use:
+
+  .. code:: bibtex
+
+     @software{simi_2024_12729251,
+         author       = {Simi, Luca},
+         title        = {tda-mapper},
+         month        = jul,
+         year         = 2024,
+         publisher    = {Zenodo},
+         version      = {v0.7.3},
+         doi          = {10.5281/zenodo.12729251},
+         url          = {https://doi.org/10.5281/zenodo.12729251}
+     }
+
+- **Methodology**: For the preprint, you can use:
+
+  .. code:: bibtex
+
+     @misc{simi_2024_11187959,
+         author       = {Simi, Luca},
+         title        = {{A Scalable Approach for Mapper via Vantage Point 
+                         Trees}},
+         month        = may,
+         year         = 2024,
+         publisher    = {Zenodo},
+         doi          = {10.5281/zenodo.11187959},
+         url          = {https://doi.org/10.5281/zenodo.11187959}
+     }
+
+
 .. toctree::
+   :caption: User's Guide
    :maxdepth: 1
 
    quickstart
    examples 
-   citations
+
+
+.. toctree::
+   :caption: API Reference
+   :maxdepth: 1
+
    apiref

docs/source/quickstart.rst

@@ -1,6 +1,42 @@
 Quick Start
+===========
+
+
+Installation
+------------
+
+To install the latest version uploaded on PyPI
+
+.. code:: bash
+
+   pip install tda-mapper
+
+
+Development
 -----------
 
+- To install the latest version with dev dependencies
+
+.. code:: bash
+
+   pip install tda-mapper[dev]
+
+- To install from the latest commit on main branch
+
+.. code:: bash
+
+   pip install git+https://github.com/lucasimi/tda-mapper-python
+
+- To install from the latest commit of develop branch
+
+.. code:: bash
+
+   pip install git+https://github.com/lucasimi/tda-mapper-python@develop
+
+
+How To Use
+----------
+
 Here's a minimal example using the **circles dataset** from
 ``scikit-learn`` to demonstrate how to use **tda-mapper**:
 
@@ -37,5 +73,18 @@ Here's a minimal example using the **circles dataset** from
 More examples can be found in the
 `documentation <https://tda-mapper.readthedocs.io/en/main/>`__.
 
+Interactive App
+---------------
+
+You can explore a live demo of **tda-mapper** directly on
+`Streamlit Cloud <https://tda-mapper-app.streamlit.app/>`__,
+or run it locally using the following:
+
+.. code:: bash
+
+   pip install -r app/requirements.txt
+   streamlit run app/streamlit_app.py
+
+
 .. |Original Dataset| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset.png
 .. |Mapper Graph| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean.png