Merge pull request #166 from janash/doc-theme-update

update theme for docs

{{cookiecutter.repo_name}}/docs/README.md

@@ -1,15 +1,25 @@
 # Compiling {{cookiecutter.project_name}}'s Documentation
 
 The docs for this project are built with [Sphinx](http://www.sphinx-doc.org/en/master/).
-To compile the docs, first ensure that Sphinx and the ReadTheDocs theme are installed.
+To compile the docs, first ensure that the necessary dependencies are installed.
 
 {% if (cookiecutter.dependency_source == 'Prefer conda-forge over the default anaconda channel with pip fallback' or cookiecutter.dependency_source == 'Prefer default anaconda channel with pip fallback') %}
+
+You can use the provided `requirements.yaml` file to create a conda environment with the necessary dependencies by running
+
+```bash
+conda env create -f requirements.yaml
+```
+
+if you wish to install dependencies in your current environment, you can do
+
 ```bash
-conda install sphinx sphinx_rtd_theme 
+conda env update --file requirements.yaml
 ```
+
 {% elif cookiecutter.dependency_source == 'Dependencies from pip only (no conda)' %}
 ```bash
-pip install sphinx sphinx_rtd_theme
+pip install sphinx pydata-sphinx-theme sphinx-copybutton sphinx-design
 ```
 {% endif %}
 
@@ -18,6 +28,9 @@ Once installed, you can use the `Makefile` in this directory to compile static H
 make html
 ```
 
+The documentation contains default pages for "Getting Started", "User Guide", "Developer Guide" and API reference. 
+We recommend adopting these sections of documentation for your project to ensure comprehensive documentation for all aspects of your project.
+
 The compiled docs will be in the `_build` directory and can be viewed by opening `index.html` (which may itself 
 be inside a directory called `html/` depending on what version of Sphinx is installed).
 

{{cookiecutter.repo_name}}/docs/conf.py

@@ -50,8 +50,11 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    'sphinx_design',
+    'sphinx_copybutton',    
 ]
 
+
 autosummary_generate = True
 napoleon_google_docstring = False
 napoleon_use_param = False
@@ -90,7 +93,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

{{cookiecutter.repo_name}}/docs/developer_guide.rst

@@ -0,0 +1,4 @@
+Developer Guide
+===============
+
+This page details how to contribute to {{cookiecutter.project_name}}. 

{{cookiecutter.repo_name}}/docs/getting_started.rst

@@ -1,4 +1,9 @@
 Getting Started
 ===============
 
-This page details how to get started with {{cookiecutter.project_name}}. 
+
+You might choose to write an overview tutorial or set of tutorials.
+
+.. code-block:: python
+    
+    import {{cookiecutter.repo_name}}

{{cookiecutter.repo_name}}/docs/index.rst

@@ -6,18 +6,70 @@
 Welcome to {{cookiecutter.project_name}}'s documentation!
 =========================================================
 
+.. grid:: 1 1 2 2
+
+    .. grid-item-card:: Getting Started
+      :margin: 0 3 0 0
+
+      Learn the basics of using {{cookiecutter.project_name}}.
+
+      .. button-link:: ./getting_started.html
+         :color: primary
+         :outline:
+         :expand:
+
+         To the Getting Started Guide
+
+
+
+    .. grid-item-card::  User Guide
+      :margin: 0 3 0 0
+
+      An in-depth guide for users.
+
+      .. button-link:: ./user_guide.html
+         :color: primary
+         :outline:
+         :expand:
+
+         To the User Guide
+
+
+
+    .. grid-item-card:: API Reference
+      :margin: 0 3 0 0
+
+      How to use the API of {{cookiecutter.project_name}}.
+
+      .. button-link:: ./api.html
+         :color: primary
+         :outline:
+         :expand:
+
+         To the API Reference.
+
+
+
+    .. grid-item-card::  Developer Guide
+      :margin: 0 3 0 0
+
+      How to contribute to {{cookiecutter.project_name}}.
+
+      .. button-link:: ./developer_guide.html
+         :color: primary
+         :outline:
+         :expand:
+
+         To the Developer Guide
+
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :hidden:
+   :titlesonly:
 
    getting_started
+   user_guide
    api
+   developer_guide
 
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

{{cookiecutter.repo_name}}/docs/requirements.yaml

@@ -1,15 +1,29 @@
-name: docs
+name: docs_{{cookiecutter.project_name}}
 channels:
+{% if cookiecutter.dependency_source == 'Prefer conda-forge over the default anaconda channel with pip fallback' %}
+  - conda-forge
+{% endif %}
+  - defaults
 dependencies:
     # Base depends
   - python
   - pip
+  {% if cookiecutter.dependency_source == 'Prefer conda-forge over the default anaconda channel with pip fallback' %}
+  - pydata-sphinx-theme
+  - sphinx-design
+  - sphinx-copybutton
+{% endif %}
 
 {% if cookiecutter.dependency_source == 'Prefer default anaconda channel with pip fallback' %}
   # Pip-only installs
   - pip:
+    - -e ../
+    - pydata-sphinx-theme
+    - sphinx-design
+    - sphinx-copybutton
 {% else %}
 
     # Pip-only installs
-  #- pip:
+  - pip:
+    - -e ../
 {% endif %}

{{cookiecutter.repo_name}}/docs/user_guide.rst

@@ -0,0 +1,4 @@
+User Guide
+===============
+
+This page details how to use {{cookiecutter.project_name}}.