Change the documentation theme to furo. (#53)

Author: tobiasraabe

README.rst

@@ -21,6 +21,10 @@
 .. image:: https://codecov.io/gh/pytask-dev/pytask/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/pytask-dev/pytask
 
+.. image:: https://results.pre-commit.ci/badge/github/pytask-dev/pytask/main.svg
+    :target: https://results.pre-commit.ci/latest/github/pytask-dev/pytask/main
+    :alt: pre-commit.ci status
+
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 
@@ -31,8 +35,9 @@
 Features
 --------
 
-In its highest aspirations, pytask tries to be pytest as a build system. Its features
-include:
+In its highest aspirations, pytask tries to be pytest as a build system. It's main
+purpose is to facilitate reproducible research by automating workflows in research
+projects. Its features include:
 
 - **Automatic discovery of tasks.**
 
@@ -57,11 +62,11 @@ explanations/why_do_i_need_a_build_system.html>`_ if you do not know or are not
 convinced that you need a build system.
 
 
-.. start-installation
-
 Installation
 ------------
 
+.. start-installation
+
 pytask is available on `Anaconda.org <https://anaconda.org/pytask/pytask>`_. Install the
 package with
 

docs/_static/css/custom.css

@@ -3,44 +3,12 @@ div.prompt {
     display: none;
 }
 
-/* Getting started index page */
-
-/* Float four columns side by side */
-.column {
-  float: left;
-  width: 45%;
-  padding: 10px 10px;
-}
-
-/* Remove extra left and right margins, due to padding in columns */
-.row {margin: 0 -5px;}
-
-/* Clear floats after the columns */
-.row:after {
-  content: "";
-  display: table;
-  clear: both;
-}
-
-/* Style the counter cards */
-.card {
-  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2); /* this adds the "card" effect */
-  padding: 16px;
-  text-align: center;
-  background-color: #fff;
-}
-
-/* Responsive columns - one column layout (vertical) on small screens */
-@media screen and (max-width: 600px) {
-  .column {
-    width: 100%;
-    display: block;
-    margin-bottom: 20px;
-  }
+img.card-img-top {
+    height: 52px;
 }
 
 a#index-link {
-    color: #3E4349;
+    color: #333;
     text-decoration: none;
 }
 

docs/api.rst

@@ -0,0 +1,11 @@
+API Reference
+=============
+
+The following documents are auto-generated and not carefully edited. They provide direct
+access to the source code and the docstrings.
+
+.. toctree::
+   :titlesonly:
+
+   /autoapi/pytask/index
+   /autoapi/_pytask/index

docs/changes.rst

@@ -15,6 +15,7 @@ all releases are available on `Anaconda.org <https://anaconda.org/pytask/pytask>
 - :gh:`50` implements correct usage of singular and plural in collection logs.
 - :gh:`51` allows to invoke pytask through the Python interpreter with ``python -m
   pytask`` which will add the current path to ``sys.path``.
+- :gh:`53` changes the theme of the documentation to furo.
 
 
 0.0.10 - 2020-11-18

docs/conf.py

@@ -42,6 +42,7 @@
     "sphinx_copybutton",
     "sphinx_autodoc_typehints",
     "sphinx_click",
+    "sphinx_panels",
     "autoapi.extension",
 ]
 
@@ -52,6 +53,9 @@
 
 suppress_warnings = ["ref.python"]
 
+pygments_style = "sphinx"
+pygments_dark_style = "monokai"
+
 # -- Extensions configuration ----------------------------------------------------------
 
 # Configuration for autodoc.
@@ -93,8 +97,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for a list of
 # built-in themes.
-
-html_theme = "alabaster"
+html_theme = "furo"
 
 # Add any paths that contain custom static files (such as style sheets) here, relative
 # to this directory. They are copied after the built-in static files, so a file named
@@ -103,19 +106,38 @@
 
 # The name of an image file (within the static path) to use as favicon of the docs.
 # This file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
-html_favicon = "_static/images/pytask.ico"  # noqa: E800
+html_logo = "_static/images/pytask_w_text.svg"
+
+# The name of an image file (within the static path) to use as favicon of the docs.
+# This file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
+html_favicon = "_static/images/pytask.ico"
 
+# Add any paths that contain custom static files (such as style sheets) here, relative
+# to this directory. They are copied after the builtin static files, so a file named
+# "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+# If false, no module index is generated.
+html_domain_indices = True
+
+# If false, no index is generated.
+html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = True
+
 html_theme_options = {
-    "extra_nav_links": {"On Github": "https://github.com/pytask-dev/pytask"},
-    "logo": "images/pytask_w_text.svg",
-    "logo_name": False,
-    "github_button": False,
-    "github_user": "pytask-dev",
-    "github_repo": "pytask",
-    "font_family": '"Avenir Next", Calibri, "PT Sans", sans-serif',
-    "head_font_family": '"Avenir Next", Calibri, "PT Sans", sans-serif',
+    "sidebar_hide_name": True,
+    "navigation_with_keys": True,
 }
 
 

docs/explanations/design.rst

@@ -4,10 +4,9 @@ Design
 The design of pytask has some key objectives.
 
 1. The interface must be simple, easy-to-learn, and may have synergies with pytest. It
-   is important that even users without a strong background in computer science are able
-   to use pytask.
+   is important that even users without a strong background in computer science or
+   programming are able to use pytask.
 
 2. pytask must be easily extensible via plugins. Developers of pytask are naturally
    unaware of all the possible applications of a build system. Thus, they must focus on
-   the host application and the design of the entry-points. This will also reduce the
-   amount of maintenance.
+   the host application and the design of the entry-points.

docs/explanations/pluggy.rst

@@ -8,7 +8,7 @@ mechanism to achieve extensibility is called :term:`hooking`.
 
 At certain points, pytask, or more generally the host, implements entry-points which are
 called hook specifications. At these entry-points the host sends a message to all
-plugins which use this entry-point. The recipient of the message is implemented by the
+plugins which target this entry-point. The recipient of the message is implemented by the
 plugin and called a hook implementation. The hook implementation receives the message
 and can decide whether to send a response or not. Then, the host receives the responses
 and can decide whether to process all or just the first valid return.
@@ -17,7 +17,7 @@ In contrast to some other mechanisms to change the behavior of a program (like m
 overriding, monkey patching), hooking excels at allowing multiple plugins to work
 alongside each other.
 
-Thus, it is the host's responsibility to design the entry-points in such a way that
+It is the host's responsibility to design the entry-points in a way such that
 
 - plugins can target very specific entry-points of the application and achieve their
   goal efficiently.
@@ -26,12 +26,13 @@ Thus, it is the host's responsibility to design the entry-points in such a way t
   the complexity of plugin's provided functionality.
 
 
-.. rubric:: References
+References
+----------
 
 .. [1] `pluggy's documentation <https://pluggy.readthedocs.io/en/latest/>`_.
 
 .. [2] `A talk by Floris Bruynooghe about pluggy and pytest
        <https://youtu.be/zZsNPDfOoHU>`_.
 
 .. [3] `An introduction to pluggy by Kracekumar Ramaraju
-       <https://kracekumar.com/post/build_plugins_with_pluggy>`
+       <https://kracekumar.com/post/build_plugins_with_pluggy>`_.

docs/explanations/why_another_build_system.rst

@@ -2,45 +2,54 @@ Why another build system?
 =========================
 
 There are a lot of build systems out there with existing communities who accumulated a
-lot of experience over time. So why go through the hassle of creating another build
-system?
+lot of experience over time. So why bother creating another build system?
 
 pytask is created having a particular audience in mind. Many researchers are not
-computer scientists first, but acquired some programming skills throughout their
-careers. This means a build system must be extremely user-friendly or provide a `steep
-learning curve <https://english.stackexchange.com/a/6226>`_, because it is only a tool.
-Since pytask resembles pytest in some ways, users have an easier time switching to
-pytask and feel more comfortable.
+computer scientists first. Instead, they acquired some programming skills throughout
+their careers. Thus, a build system must be extremely user-friendly and provide a `steep
+learning curve <https://english.stackexchange.com/a/6226>`_. Since pytask resembles
+pytest in many ways, users have an easy time switching to pytask and feel more
+comfortable and empowered.
 
-The second reason is that pytest seems to provide the ideal architecture for a build
-system. Its plugin-based design allows for customization at every level. A build system
-is a tool which can be deployed in many different environments whose requirements are
-not foreseeable by the developer. If it is easy for users / developers to write plugins
-which extend the functionality of pytask it is more valuable. If there is any question
-whether pytest's architecture is really suited for this, one should look at the success
-of pytest, its wide-spread adoption, and its over 800 plugins.
+pytask inherits many of pytest's best ideas. The most useful one is probably the debug
+mode which enables users to jump right into the code where the error happened. It
+shortens feedback loops, increases productivity, and facilitates error detection.
+
+pytest provides the ideal architecture for a build system. Its plugin-based design
+allows for customization at every level. A build system is a tool which can be deployed
+in many different contexts whose requirements are not foreseeable by core developers.
+Thus, it is important to enable users and developers to adjust pytask to their needs.
+pytest with its 800+ plugins is a huge success story in this regard. In turn, pytask may
+attract many people from different backgrounds who contribute back to the main
+application and help the broader community.
 
 
 Alternatives
 ------------
 
-Here is a list of other build systems and their advantages and disadvantages compared to
-pytask. The list helps to define pytask's niche and to collect new ideas to improve
-pytask.
+There are some alternatives to pytask which are listed below. The short descriptions
+don't do them justice and you should check them out to see which build system is best
+for you.
+
+Feel free to contribute to this list and add points which made you chose some build
+system over pytask. The list also serves as an inspiration for pytask to adopt features
+present in other build systems.
 
 
 `snakemake <https://github.com/snakemake/snakemake>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Pros
 
-- Mature library.
-- Is the build system for some research projects.
+- Very mature library and probably the most adapted library in the realm of scientific
+  workflow software.
 - Can scale to clusters and use Docker images.
 - Supports Python and R.
+- Automatic test case generation.
 
 Cons
 
+- No debug mode.
 - Need to learn snakemake's syntax which is a mixture of Make and Python.
 - Seems to have no plugin system.
 
@@ -55,7 +64,7 @@ Pros
 
 Cons
 
-- Focus on compiling binaries.
+- Focus on compiling binaries, not research projects.
 - Bus factor of 1.
 
 
@@ -74,7 +83,7 @@ Derivatives:
 
 Cons
 
-- written in Go.
+- Written in Go.
 
 
 `Scons <https://github.com/SCons/scons>`_
@@ -99,4 +108,5 @@ Pros
 Cons
 
 - Development is paused.
+- Designed for compiling software.
 - No plugin system, but extensible interfaces.