From 0571e1efcc04a798d162d0de8153d100a20c9d34 Mon Sep 17 00:00:00 2001 From: Jessica Nash Date: Sat, 12 Nov 2022 13:20:11 -0500 Subject: [PATCH 1/4] update theme for docs this commit changes the default theme from sphinx_rtd_theme to pydata_sphinx_theme and adds the sphinx_design plugin. Pages for user guides and developer guides are also added. --- {{cookiecutter.repo_name}}/docs/conf.py | 4 +- .../docs/developer_guide.rst | 4 ++ {{cookiecutter.repo_name}}/docs/index.rst | 61 ++++++++++++++++--- .../docs/requirements.yaml | 10 +++ .../docs/user_guide.rst | 4 ++ 5 files changed, 72 insertions(+), 11 deletions(-) create mode 100644 {{cookiecutter.repo_name}}/docs/developer_guide.rst create mode 100644 {{cookiecutter.repo_name}}/docs/user_guide.rst diff --git a/{{cookiecutter.repo_name}}/docs/conf.py b/{{cookiecutter.repo_name}}/docs/conf.py index 34f653d..a7577f7 100644 --- a/{{cookiecutter.repo_name}}/docs/conf.py +++ b/{{cookiecutter.repo_name}}/docs/conf.py @@ -50,6 +50,8 @@ 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks', + 'sphinx_design' + ] autosummary_generate = True @@ -90,7 +92,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 diff --git a/{{cookiecutter.repo_name}}/docs/developer_guide.rst b/{{cookiecutter.repo_name}}/docs/developer_guide.rst new file mode 100644 index 0000000..885901a --- /dev/null +++ b/{{cookiecutter.repo_name}}/docs/developer_guide.rst @@ -0,0 +1,4 @@ +Developer Guide +=============== + +This page details how to contribute to {{cookiecutter.project_name}}. diff --git a/{{cookiecutter.repo_name}}/docs/index.rst b/{{cookiecutter.repo_name}}/docs/index.rst index d22504b..e7ea602 100644 --- a/{{cookiecutter.repo_name}}/docs/index.rst +++ b/{{cookiecutter.repo_name}}/docs/index.rst @@ -6,18 +6,59 @@ Welcome to {{cookiecutter.project_name}}'s documentation! ========================================================= -.. toctree:: - :maxdepth: 2 - :caption: Contents: +.. grid:: 2 - getting_started - api + .. grid-item-card:: Getting Started + + Learn the basics of using {{cookiecutter.project_name}}. + .. button-link:: ./getting_started.html + :color: primary + :outline: + :expand: + To the Getting Started Guide -Indices and tables -================== + -------------------------------- + + .. grid-item-card:: User Guide + + An in-depth guide for users + + .. button-link:: ./user_guide.html + :color: primary + :outline: + :expand: + + To the User Guide + + -------------------------- + +.. grid:: 2 + + .. grid-item-card:: API Reference + + 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 + + How to contribute to {{cookiecutter.project_name}} + + .. button-link:: ./developer_guide.html + :color: primary + :outline: + :expand: + + To the Developer Guide + + -------------------------- -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/{{cookiecutter.repo_name}}/docs/requirements.yaml b/{{cookiecutter.repo_name}}/docs/requirements.yaml index 052965f..8e9f474 100644 --- a/{{cookiecutter.repo_name}}/docs/requirements.yaml +++ b/{{cookiecutter.repo_name}}/docs/requirements.yaml @@ -1,13 +1,23 @@ name: docs 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 +{% endif %} {% if cookiecutter.dependency_source == 'Prefer default anaconda channel with pip fallback' %} # Pip-only installs - pip: + - pydata-sphinx-theme + - sphinx-design {% else %} # Pip-only installs diff --git a/{{cookiecutter.repo_name}}/docs/user_guide.rst b/{{cookiecutter.repo_name}}/docs/user_guide.rst new file mode 100644 index 0000000..b747e6b --- /dev/null +++ b/{{cookiecutter.repo_name}}/docs/user_guide.rst @@ -0,0 +1,4 @@ +User Guide +=============== + +This page details how to use {{cookiecutter.project_name}}. From 35021f58a7f4ffd10b4de49ac777ee3bc879db06 Mon Sep 17 00:00:00 2001 From: Jessica Nash Date: Mon, 14 Nov 2022 16:44:08 -0500 Subject: [PATCH 2/4] make grid responsive --- {{cookiecutter.repo_name}}/docs/index.rst | 31 +++++++++++++++-------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/{{cookiecutter.repo_name}}/docs/index.rst b/{{cookiecutter.repo_name}}/docs/index.rst index e7ea602..82fe0bc 100644 --- a/{{cookiecutter.repo_name}}/docs/index.rst +++ b/{{cookiecutter.repo_name}}/docs/index.rst @@ -6,9 +6,10 @@ Welcome to {{cookiecutter.project_name}}'s documentation! ========================================================= -.. grid:: 2 +.. grid:: 1 1 2 2 .. grid-item-card:: Getting Started + :margin: 0 3 0 0 Learn the basics of using {{cookiecutter.project_name}}. @@ -19,11 +20,12 @@ Welcome to {{cookiecutter.project_name}}'s documentation! To the Getting Started Guide - -------------------------------- + .. grid-item-card:: User Guide + :margin: 0 3 0 0 - An in-depth guide for users + An in-depth guide for users. .. button-link:: ./user_guide.html :color: primary @@ -32,11 +34,10 @@ Welcome to {{cookiecutter.project_name}}'s documentation! To the User Guide - -------------------------- - -.. grid:: 2 + .. grid-item-card:: API Reference + :margin: 0 3 0 0 How to use the API of {{cookiecutter.project_name}}. @@ -47,11 +48,12 @@ Welcome to {{cookiecutter.project_name}}'s documentation! To the API Reference. - -------------------------------- + .. grid-item-card:: Developer Guide + :margin: 0 3 0 0 - How to contribute to {{cookiecutter.project_name}} + How to contribute to {{cookiecutter.project_name}}. .. button-link:: ./developer_guide.html :color: primary @@ -59,6 +61,15 @@ Welcome to {{cookiecutter.project_name}}'s documentation! :expand: To the Developer Guide - - -------------------------- + + +.. toctree:: + :maxdepth: 2 + :hidden: + :titlesonly: + + getting_started + user_guide + api + developer_guide From f9d3d6a51beb4844be939d65c4a585ae972b9815 Mon Sep 17 00:00:00 2001 From: Jessica Nash Date: Thu, 9 Nov 2023 12:41:08 -0500 Subject: [PATCH 3/4] update conf.py, requirements.yaml for new doc theme --- {{cookiecutter.repo_name}}/docs/conf.py | 5 +++-- {{cookiecutter.repo_name}}/docs/getting_started.rst | 7 ++++++- {{cookiecutter.repo_name}}/docs/requirements.yaml | 8 ++++++-- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/{{cookiecutter.repo_name}}/docs/conf.py b/{{cookiecutter.repo_name}}/docs/conf.py index a7577f7..ab70317 100644 --- a/{{cookiecutter.repo_name}}/docs/conf.py +++ b/{{cookiecutter.repo_name}}/docs/conf.py @@ -50,10 +50,11 @@ 'sphinx.ext.napoleon', 'sphinx.ext.intersphinx', 'sphinx.ext.extlinks', - 'sphinx_design' - + 'sphinx_design', + 'sphinx_copybutton', ] + autosummary_generate = True napoleon_google_docstring = False napoleon_use_param = False diff --git a/{{cookiecutter.repo_name}}/docs/getting_started.rst b/{{cookiecutter.repo_name}}/docs/getting_started.rst index a00ecb4..e47ac7b 100644 --- a/{{cookiecutter.repo_name}}/docs/getting_started.rst +++ b/{{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}} diff --git a/{{cookiecutter.repo_name}}/docs/requirements.yaml b/{{cookiecutter.repo_name}}/docs/requirements.yaml index 8e9f474..b9fdff0 100644 --- a/{{cookiecutter.repo_name}}/docs/requirements.yaml +++ b/{{cookiecutter.repo_name}}/docs/requirements.yaml @@ -1,4 +1,4 @@ -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 @@ -11,15 +11,19 @@ dependencies: {% 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 %} From df1f713e3b20c341e8457790babb8fa2c850ba2e Mon Sep 17 00:00:00 2001 From: Jessica Nash Date: Thu, 9 Nov 2023 12:57:36 -0500 Subject: [PATCH 4/4] update README in docs folder --- {{cookiecutter.repo_name}}/docs/README.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.repo_name}}/docs/README.md b/{{cookiecutter.repo_name}}/docs/README.md index f30cb4b..8c555d1 100644 --- a/{{cookiecutter.repo_name}}/docs/README.md +++ b/{{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).