Fix: breakout docs into separate pages with separate goals and update left bar links

Author: lwasser

documentation/package-documentation-best-practices.md

@@ -31,6 +31,16 @@ have 4 elements on the home page of their documentation:
 * **Community:** Instructions for how to help and/or get involved. This section might include a development guide. 
 * **Documentation:** The actual project documentation. You may have two sections of documentation - the user facing documentation and your API reference. 
 
+
+```{figure} ../images/geopandas-documentation-landing-page.png
+---
+name: directive-fig
+width: 80%
+alt: Image showing the landing page for GeoPandas documentation which has 4 sections including Getting started, Documentation, About GeoPandas, Community. 
+---
+The documentation landing page of GeoPandas, a spatial Python library, has the 4 element specified above. Notice that the landing page is simple and directs users to each element using a Sphinx card.
+```
+
 NOTE: in many cases you can include your **README** file and your **CONTRIBUTING** files 
 in your documentation given those files may have some of the components listed above.
 
@@ -43,11 +53,6 @@ Below is an example of doing this using `myst` syntax.
 ````
 `````
 
-## Documentation tutorials 
-
-* sphinx gallery vs ()
-* best practices... 
-
 ## API's and Docstrings
 
 ### What is an API?

documentation/python-package-documentation-tools.md

@@ -1,9 +1,33 @@
 # Python Package Documentation
 
-In addition to your README, CONTRIBUTING and DEVELOPMENT guides, 
+<!-- TODO: make this into include files so we can have a summary 
+important points page -->
+
+```{important}
+
+## Take Aways: Key Python Package Tools to Use
+
+* Use Sphinx to build your documentation
+* Publish your documentation on ReadTheDocs (or GitHub pages if you are more advanced and also prefer to maintain your website locally)
+* Use `myST` syntax to write your documentation 
+* Use sphinx gallery to write tutorials using .py files that automagically have downloadable .py and jupyter notebook files. Use nbsphinx if you prefer writing tutorials in jupyter notebook format and don't need a grid formatted gallery. 
+
+```
+
+In addition to your:
+* [README.md file](readme-file-best-practices.md), 
+* [CONTRIBUTING.md and development guides and LICENSE file](contributing-file.md),
+
 you should also have user-facing documentation for your Python 
-package. Below we you will learn about the most common tools that 
-are used to build Python packaging documentation. 
+package. Most often, user-facing documentation is contained on a hosted 
+website. 
+
+Below you will learn about the most common tools that 
+are used to build scientific Python packaging documentation. You will also 
+learn about hosting options for your documentation. 
+
+Here, we focus on tools and infrastructure that you can use. 
+[Click here if you want to learn more about documentation best practices](package-documentation-best-practices.md).
 
 ```{note}
 Examples of documentation that we love:
@@ -16,31 +40,38 @@ Examples of documentation that we love:
 ```
 
 
-## What tools to use to build your documentation: sphinx
+## Sphinx, the most common tool used in the scientific Python ecosystem 
 
-Most python packages use [sphinx](https://www.sphinx-doc.org/) to build their documentation. 
+Most scientific Python packages use [sphinx](https://www.sphinx-doc.org/) to 
+build their documentation. As such, we will focus on sphinx in this guide. 
 
-```{tip} 
-Sphinx is a static-site generator. A static site generator is a tool that creates 
+Sphinx is a [static-site generator](https://www.cloudflare.com/learning/performance/static-site-generator/). A static site generator is a tool that creates 
 html for a website based upon a set of templates. Sphinx is written 
 using Python tool which 
 is why it's commonly used in the Python ecosystem. 
 
-There are however other tools that could be used such as [mkdocs](https://www.mkdocs.org/). We won't 
-got into others tools in this guide given sphinx is currently the most 
-popular in the scientific Python ecosystem. However, you are welcome to use whatever documentation tool that you prefer for your Python package development! 
+```{tip} 
+There are other static site generator tools that could be used to create user-facing documentation including 
+ [mkdocs](https://www.mkdocs.org/). We won't 
+discuss others tools in this guide given sphinx is currently the most 
+popular in the scientific Python ecosystem. 
+
+You are welcome to use whatever documentation tool that you prefer for your Python package development! 
 ```
 
-Sphinx can be extended with various elements including themes and directives (extensions) as follows:
+### Sphinx sites can be optimized for documentation with extensions and themes 
+
+The functionality of sphinx can be extended using extensions and themes. A few 
+examples include:
 
 * You can apply documentation themes for quick generation of beautiful documentation.
-* You can [automatically create documentation for your package's functions and classes (API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
-* You can [run and testing code examples in your docstrings using doctest](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html)
-* While sphinx natively supports the rst syntax. You can add custom syntax parsers to support easier to write syntax such as [myst](https://myst-parser.readthedocs.io/) .
+* You can [automatically create documentation for your package's functions and classes (that package's API) from docstrings in your code using the autodoc extension](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
+* You can [run and test code examples in your docstrings using the doctest extension](https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html)
+* While sphinx natively supports the `rST` syntax. You can add custom syntax parsers to support easier-to-write syntax using tools such as [myst](https://myst-parser.readthedocs.io/).
 
-While you are free to use whatever sphinx theme you prefer,
-the most common modern templates that recommend for the Python scientific 
-community are:  
+You are free to use whatever sphinx theme that you prefer. However, the most 
+common sphinx themes that we recommend for the Python scientific 
+community include:  
 
 * [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/) 
 * [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/)
@@ -57,46 +88,113 @@ There are three commonly used syntaxes for creating Python documentation:
 1. [markdown](https://www.markdownguide.org/): Markdown is an easy-to-learn text 
 syntax. It is the default syntax use in Jupyter Notebooks. There are tools that you can add to a sphinx website that allow it to render markdown as html. However, using markdown to write documentation has limitations. For instance if you want to add references, 
 colored call out blocks and other custom elements to your documentation, you will 
-need to use either myST or rST.
-1. [rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). rST is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years given the limitations associated with markdown. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
-1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of vanilla of `markdown` and `rST` syntax. It is a nice option if you are more comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality 
+need to use either **myST** or **rST**.
+1. [rST (ReStructured Text):](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html). **rST** is the native syntax that sphinx supports. rST was the default syntax used for documentation for many years given the limitations of markdown. However, in recent years myST has risen to the top as a favorite for documentation given the flexibility that it allows.
+1. [myST:](https://myst-parser.readthedocs.io/en/latest/intro.html) myST is a combination of vanilla of `markdown` and `rST` syntax. It is a nice option if you are comfortable writing markdown. `myst` is preferred by many because it offers both the rich functionality 
 of rST combined with a simple-to-write markdown syntax. 
 
-While you can chose to use any of the syntaxes listed above, `myST` is a 
-preferred syntax to because:
+While you can chose to use any of the syntaxes listed above, we suggest using 
+`myST` because:
 
 * It is a simpler syntax and thus easier to learn;
+* The above simplicity will make it easier for more people to contribute to your documentation. 
 * Most of your core python package text files, such as your README.md file, are already in `.md` format
-* `GitHub` and `Jupyter Notebooks` support this default syntax/file format.
+* `GitHub` and `Jupyter Notebooks` support markdown thus it's more widely used in the scientific ecosystem. 
 
-There is no wrong or right when choosing a syntax to write your documentation. 
-Choose whichever syntax works best for you and your community! 
 
 ```{tip}
-If you are on the fence about myST vs rst, you might find that *myST* is easier 
+If you are on the fence about myST vs rst, you might find that **myST** is easier 
 for more people to contribute to.  
 ```
 
-## How to host your Python package documentation
+## Sphinx extensions to support python package tutorials 
+
+Adding well constructed tutorials to your package will make it easier for someone 
+new to begin using your package. 
+
+There are two sphinx tools that make it easy to add tutorials to your package:
+
+* [Sphinx Gallery](https://sphinx-gallery.github.io/stable/index.html) and 
+* [NbSphinx](https://nbsphinx.readthedocs.io/en/latest/)
+
+Both of these tools act as sphinx extensions and:
+
+* Support creating a gallery type page in your sphinx documentation where users can explore tutorials via thumbnails.
+* Run the code in your tutorials adding another level of "testing" for your package as used. 
+* Render your tutorials with Python code and plot outputs
 
-We suggest that you setup a website to host your documentation. There are two 
-ways to do quickly create a documentation website:
+### [sphinx gallery:](https://sphinx-gallery.github.io/stable/index.html) 
 
-1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. 
-2. You can host your documentation using [Read the Docs](https://readthedocs.org/).
+If you prefer to write your tutorials using python **.py** scripts, you 
+may enjoy using sphinx gallery. Sphinx gallery uses **.py** files with 
+text and code sections that mimics the Jupyter Notebook format. When you build 
+your documentation, the gallery extension: 
 
-If you don't want to maintain a documentation website for your Python package, 
-we suggest using the Read the Docs website. Read the Docs allows you to:
+1. Runs the code in each tutorial: this acts as a check to ensure your package is working as you think it is!
+1. Creates a downloadable Jupyter Notebook **.ipynb** file and a  **.py** script for your tutorial that a user can quickly download and run. 
+1. Creates a rendered  **.html** page with the code elements and code outputs in a user-friendly tutorial gallery.  
+1. Creates a gallery landing page with visual thumbnails for each tutorial that you create
 
-* Quickly launch a website using the documentation found in your GitHub repository.  
-* Track versions of your documentation as you release updates.
+<!-- TODO: Add thumbnails out tutorial outputs  -->
 
-## Tutorials 
-* sphinx gallery... 
+### Sphinx Gallery benefits 
+* easy-to-download notebook and .py outputs for each tutorials
+* .py files are easy to work with in the GitHub pull request environment. 
+* Nice gridded gallery output 
+
+#### Sphinx gallery challenges 
+
+The downsides of using sphinx gallery include: 
+
+* the **.py** files can be finicky to configure, particularly if you have matplotlib plot outputs. 
+
+For example: To make allow for plots to render, you need to name each file with `plot_` 
+at the beginning. 
+
+* Many users these days are used to working in Jupyter Notebooks. .py may be slightly less user friendly to work with 
+
+These nuances can make it challenging for potential contributors to add 
+tutorials to your package. This can also present maintenance challenge.
+
+Add about the gallery setup - 
+```bash
+tutorials/
+    index.rst # landing page for your gallery
+    tutorial.py # a tutorial 
+    plot_tutorial.py # a tutorial that produces a plot output
+tutorial_outputs/ 
+    add fils here... 
+```
+
+### [nbsphinx - tutorials using Jupyter Notebooks](https://nbsphinx.readthedocs.io/en/latest/)
+
+If you prefer to use Jupyter Notebooks to create tutorials you can use nbsphinx.
+nbsphinx operates similarly to sphinx gallery in that:
+
+* It runs your notebooks and produces outputs in the rendered tutorials 
+
+* Pro/con By default it does not support downloading of **.py** and **.ipynb** files. However you can add a [link to the notebook at the top of the page with 
+some additional conf.py settings (see: epilog settings)](https://nbsphinx.readthedocs.io/en/0.8.10/prolog-and-epilog.html)
+
+
+```{figure} ../images/python-package-documentation-nb_sphinx-gallery-output.png
+---
+name: directive-fig
+width: 80%
+alt: Image showing the gallery output provided by nbsphinx using the sphinx-gallery front end interface. 
+---
+`nbsphinx` can be combined with sphinx gallery to create a gallery of tutorials. 
+However, rather render the gallery as a grid, it lists all of the gallery 
+elements in a single column. 
+```
+
+```bash
+tutorials/
+    index.md # Landing page for your gallery
+    tutorial.ipynb # A tutorial in a jupyter notebook
+    another_tutorial.ipynb
+tutorial_outputs/ 
+    add fils here... 
+```
 
-<!-- Bells and whistles additions-->
-## Bells and whistles for your documentation 
 
-* sitemap  - for google seo 
-* other extension?? 
-* google analytics 

documentation/website-hosting-optimizing-your-docs.md

@@ -0,0 +1,49 @@
+# Hosting your Python package documentation and optimizing online content 
+
+## How to host your Python package documentation
+
+We suggest that you setup a hosting for your Python package 
+documentation. Two, free and most commonly used ways to
+quickly create a documentation website hosting environment are below. 
+
+1. You can host your documentation yourself using [GitHub Pages](https://pages.github.com/) or another online hosting service. 
+1. You can host your documentation using [Read the Docs](https://readthedocs.org/).
+
+If you don't want to maintain a documentation website for your Python package, 
+we suggest using the Read the Docs website. Read the Docs allows you to:
+
+* Quickly launch a website using the documentation found in your GitHub repository.  
+* Track versions of your documentation as you release updates.
+* Provides support for Google analytics.
+* Allows you to turn on integration with pull requests where you can view documentation build progress (success vs failure).
+
+
+
+## Optimizing your documentation so search engines (and other users) find it
+
+If you are interested in more people finding your package, you may want to 
+add some core sphinx extensions (and theme settings) that will help search 
+engines such as Google find your documentation. 
+
+
+### Google Analytics
+Some of the [sphinx themes such as the `pydata-sphinx-theme` and 
+sphinx-book-theme have built in support for google analytics](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/analytics.html#google-analytics). However, if the theme that you chose does not offer 
+Google Analytics support, you can use the [`sphinxcontrib-gtagjs` extension](https://github.com/attakei/sphinxcontrib-gtagjs). 
+This extension will add a Google Analytics site tag to each page of your 
+documentation.  
+
+### [sphinx-sitemap](https://sphinx-sitemap.readthedocs.io/en/latest/index.html)
+
+If you are interested in optimizing your documentation for search engines such as Google, you want a sitemap.xml file. You can submit this sitemap to Google and it will index your entire site. This over time can make the content on your site more visible to others when they search. 
+
+This extension is light weight.
+
+It [requires that you to add it to your sphinx `conf.py` extension list and site your documentation base url.](https://sphinx-sitemap.readthedocs.io/en/latest/getting-started.html).
+
+### [sphinxext.opengraph](https://github.com/wpilibsuite/sphinxext-opengraph)
+
+OpenGraph is an extension that allows you to add metadata to your documentation 
+content pages. [The OpenGraph protocol allows other websites to provide a 
+useful preview of the content on your page when shared](https://www.freecodecamp.org/news/what-is-open-graph-and-how-can-i-use-it-for-my-website/#what-is-open-graph). This is important 
+for when the pages in your documentation are shared.  

images/geopandas-documentation-landing-page.png

@@ -112,10 +112,11 @@ to see here, [we invite you to open an issue on GitHub that details any changes
 :caption: Documentation
 
 Documentation Overview <documentation/index>
+Package Documentation Best Practices <documentation/package-documentation-best-practices>
+Package Documentation Tools <documentation/python-package-documentation-tools>
+Host & Help People Find Your Docs <documentation/website-hosting-optimizing-your-docs>
 The README File <documentation/readme-file-best-practices.md>
 Contributing & License files <documentation/contributing-file>
-Package Documentation Tools <documentation/python-package-documentation-tools>
-Package Documentation Best Practices <documentation/package-documentation-best-practices>
 ```
 
 ```{toctree}