Restructure documentation navigation bar

.gitignore

@@ -24,7 +24,6 @@ dist/
 
 # doc generated
 docs/_build
-docs/_templates
 wiki/
 
 # testing coverage and cache

CONTRIBUTING.md

@@ -0,0 +1,154 @@
+# Contributing
+
+We absolutely welcome contributions and we hope that this guide will facilitate
+an understanding of the PyVista code repository. It is important to note that
+the  PyVista software package is maintained on a volunteer basis and thus we
+need to foster a community that can support user questions and develop new
+features to make this software a useful tool for all users.
+
+This page is dedicated to outline where you should start with your question,
+concern, feature request, or desire to contribute.
+
+
+## Questions
+
+For general questions about the project, its applications, or about software
+usage, please create an issue in the [pyvista/pyvista-support](https://github.com/pyvista/pyvista-support)
+repository where the community can collectively address your questions.
+You are also welcome to join us on join us on [Slack](http://slack.opengeovis.org)
+or send one of the developers an email.
+The project support team can be reached at [info@pyvista.org](mailto:info@pyvista.org)
+
+
+For more technical questions, you are welcome to create an issue on the
+[issues page](https://github.com/pyvista/pyvista/issues) which we will address promptly.
+Through posting on the issues page, your question can be addressed by community
+members with the needed expertise and the information gained will remain
+available on the issues page for other users.
+
+
+## Reporting Bugs
+
+If you stumble across any bugs, crashes, or concerning quirks while using code
+distributed here, please report it on the [issues page](https://github.com/pyvista/pyvista/issues)
+with an appropriate label so we can promptly address it.
+When reporting an issue, please be overly descriptive so that we may reproduce
+it. Whenever possible, please provide tracebacks, screenshots, and sample files
+to help us address the issue.
+
+## Feature Requests
+
+We encourage users to submit ideas for improvements to PyVista code base!
+Please create an issue on the [issues page](https://github.com/pyvista/pyvista/issues)
+with a *Feature Request* label to suggest an improvement.
+Please use a descriptive title and provide ample background information to help
+the community implement that functionality. For example, if you would like a
+reader for a specific file format, please provide a link to documentation of
+that file format and possibly provide some sample files with screenshots to work
+with. We will use the issue thread as a place to discuss and provide feedback.
+
+## Contributing New Code
+
+If you have an idea for how to improve PyVista, please first create an issue as
+a feature request which we can use as a discussion thread to work through how to
+implement the contribution.
+
+Once you are ready to start coding and develop for PyVista, please take a look
+at the remainder of the pages in this *Development Guide*.
+
+## Licensing
+
+All contributed code will be licensed under The MIT License found in the
+repository. If you did not write the code yourself, it is your responsibility
+to ensure that the existing license is compatible and included in the
+contributed files or you can obtain permission from the original author to
+relicense the code.
+
+
+## Guidelines
+
+Through direct access to the Visualization Toolkit (VTK) via direct array
+access and intuitive Python properties, we hope to make the entire VTK library
+easily accessible to researchers of all disciplines. To further PyVista towards
+being the de facto Python interface to VTK, we need your help to make it even
+better!
+
+If you want to add one or two interesting analysis algorithms as filters,
+implement a new plotting routine, or just fix 1-2 typos - your efforts are
+welcome!
+
+
+There are three general coding paradigms that we believe in:
+
+1. **Make it intuitive**. PyVista's goal is to create an intuitive and easy
+   to use interface back to the VTK library. Any new features should have
+   intuitive naming conventions and explicit keyword arguments for users to
+   make the bulk of the library accessible to novice users.
+
+2. **Document everything!** At the least, include a docstring for any method
+   or class added. Do not describe what you are doing but why you are doing
+   it and provide a for simple use cases for the new features.
+
+3. **Keep it tested**. We aim for a high test coverage. See
+   testing for more details.
+
+
+
+There are two important copyright guidelines:
+
+4. Please do not include any data sets for which a license is not available
+   or commercial use is prohibited. Those can undermine the license of
+   the whole projects.
+
+5. Do not use code snippets for which a license is not available (e.g. from
+   stackoverflow) or commercial use is prohibited. Those can undermine
+   the license of the whole projects.
+
+
+
+## Testing
+
+After making changes, please test changes locally before creating a pull
+request. The following tests will be executed after any commit or pull request,
+so we ask that you perform the following sequence locally to track down any new
+issues from your changes.
+To run our comprehensive suite of unit tests, install all the dependencies
+listed in ``requirements.txt``, ``requirements_docs.txt``:
+
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements_docs.txt
+```
+
+Then, if you have everything installed, you can run the various test suites:
+
+
+Run the primary test suite and generate coverage report:
+
+```bash
+python -m pytest -v --cov pyvista
+```
+
+Run all code examples in the docstrings:
+
+```bash
+python -m pytest -v --doctest-modules pyvista
+```
+
+Now make sure notebooks are running
+
+```bash
+python -m pytest -v --nbval-lax --current-env --disable-warnings notebooks/*.ipynb
+python -m pytest -v --nbval-lax --current-env --disable-warnings tests/*.ipynb
+```
+
+And finally, test the documentation examples:
+
+```bash
+cd ./docs/
+make doctest
+make html
+```
+
+The finished documentation can be found in the `docs/_build/html` directory.

docs/_templates/layout.html

@@ -0,0 +1,44 @@
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{% block extrahead %}
+{{ super() }}
+
+<meta name="description" content="3D plotting and mesh analysis through a streamlined interface for the Visualization Toolkit (VTK)">
+<meta name="author" content="PyVista Developers">
+<meta name="keywords" content="python, 3D, visualization, plotting, mesh, meshviewer, vtk, open-source">
+
+<!-- this contains PyVista's Google analytics code - please don't copy/paste our tracking ID -->
+<script>
+  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+
+  ga('create', 'UA-140243896-1', 'auto');
+  ga('send', 'pageview');
+
+</script>
+{% endblock %}
+
+{% block menu %}
+    {{ super() }}
+
+    {% if menu_links %}
+        <p class="caption">
+            <span class="caption-text">
+            {% if menu_links_name %}
+                {{ menu_links_name }}
+            {% else %}
+                External links
+            {% endif %}
+            </span>
+        </p>
+        <ul>
+            {% for text, link in menu_links %}
+                <li class="toctree-l1"><a href="{{ link }}">{{ text }}</a></li>
+            {% endfor %}
+        </ul>
+    {% endif %}
+{% endblock %}

docs/conf.py

@@ -75,7 +75,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'friendly'
@@ -84,6 +84,31 @@
 todo_include_todos = False
 
 
+# -- Sphinx Gallery Options
+from sphinx_gallery.sorting import FileNameSortKey
+
+sphinx_gallery_conf = {
+    # path to your examples scripts
+    "examples_dirs": [
+        "../examples/",
+    ],
+    # path where to save gallery generated examples
+    "gallery_dirs": ["examples"],
+    # Patter to search for example files
+    "filename_pattern": r"\.py",
+    # Remove the "Download all examples" button from the top level gallery
+    "download_all_examples": False,
+    # Sort gallery example by file name instead of number of lines (default)
+    "within_subsection_order": FileNameSortKey,
+    # directory where function granular galleries are stored
+    "backreferences_dir": False,
+    # Modules for which function level galleries are created.  In
+    "doc_module": "pyvista",
+    "image_scrapers": (pyvista.Scraper(), 'matplotlib'),
+    "thumbnail_size": (350, 350),
+}
+
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -98,7 +123,13 @@
     # Format Template: https://{{ github_host|default("github.com") }}/{{ github_user }}/{{ github_repo }}/blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}{{ suffix }}
     'github_user': 'pyvista',
     'github_repo': 'pyvista',
-    'github_version': 'master/docs/'
+    'github_version': 'master/docs/',
+    'menu_links_name': 'Getting Connected',
+    'menu_links': [
+        ('<i class="fa fa-comment fa-fw"></i> Support', 'https://github.com/pyvista/pyvista-support'),
+        ('<i class="fa fa-github fa-fw"></i> Source Code', 'https://github.com/pyvista/pyvista'),
+        ('<i class="fa fa-gavel fa-fw"></i> Contributing', 'https://github.com/pyvista/pyvista/blob/master/CONTRIBUTING.md'),
+    ],
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -179,31 +210,6 @@
 notfound_no_urls_prefix = True
 
 
-# -- Sphinx Gallery Options
-from sphinx_gallery.sorting import FileNameSortKey
-
-sphinx_gallery_conf = {
-    # path to your examples scripts
-    "examples_dirs": [
-        "../examples/",
-    ],
-    # path where to save gallery generated examples
-    "gallery_dirs": ["examples"],
-    # Patter to search for example files
-    "filename_pattern": r"\.py",
-    # Remove the "Download all examples" button from the top level gallery
-    "download_all_examples": False,
-    # Sort gallery example by file name instead of number of lines (default)
-    "within_subsection_order": FileNameSortKey,
-    # directory where function granular galleries are stored
-    "backreferences_dir": False,
-    # Modules for which function level galleries are created.  In
-    "doc_module": "pyvista",
-    "image_scrapers": (pyvista.Scraper(), 'matplotlib'),
-    "thumbnail_size": (350, 350),
-}
-
-
 # -- Autosummary options
 from sphinx.ext.autosummary import Autosummary
 from sphinx.ext.autosummary import get_documenter