Refactor docs and switch to RTD theme

hynek · hynek · commit 609b10e84f5f · 2020-03-08T07:46:56.000+01:00
Our API docs are much more readable on it.

Remove testimonials, they don't serve that much and take up space.

Slightly refactor main docs page.
diff --git a/README.rst b/README.rst
@@ -27,7 +27,7 @@
 
 Its main goal is to help you to write **concise** and **correct** software without slowing down your code.
 
-.. -spiel-end-
+.. teaser-end
 
 For that, it gives you a class decorator and a way to declaratively define the attributes on that class:
 
@@ -85,35 +85,7 @@ Which in turn encourages you to write *small classes* that do `one thing well <h
 Never again violate the `single responsibility principle <https://en.wikipedia.org/wiki/Single_responsibility_principle>`_ just because implementing ``__init__`` et al is a painful drag.
 
 
-.. -testimonials-
-
-Testimonials
-============
-
-**Amber Hawkie Brown**, Twisted Release Manager and Computer Owl:
-
-  Writing a fully-functional class using attrs takes me less time than writing this testimonial.
-
-
-**Glyph Lefkowitz**, creator of `Twisted <https://twistedmatrix.com/>`_, `Automat <https://pypi.org/project/Automat/>`_, and other open source software, in `The One Python Library Everyone Needs <https://glyph.twistedmatrix.com/2016/08/attrs.html>`_:
-
-  I’m looking forward to is being able to program in Python-with-attrs everywhere.
-  It exerts a subtle, but positive, design influence in all the codebases I’ve see it used in.
-
-
-**Kenneth Reitz**, creator of `Requests <https://github.com/psf/requests>`_ (`on paper no less <https://twitter.com/hynek/status/866817877650751488>`_!):
-
-  attrs—classes for humans.  I like it.
-
-
-**Łukasz Langa**, creator of `Black <https://github.com/psf/black>`_, prolific Python core developer, and release manager for Python 3.8 and 3.9:
-
-  I'm increasingly digging your attr.ocity. Good job!
-
-
-.. -end-
-
-.. -project-information-
+.. -getting-help-
 
 Getting Help
 ============
@@ -123,6 +95,8 @@ Please use the ``python-attrs`` tag on `StackOverflow <https://stackoverflow.com
 Answering questions of your fellow developers is also great way to help the project!
 
 
+.. -project-information-
+
 Project Information
 ===================
 
diff --git a/docs/_static/attrs_logo_white.png b/docs/_static/attrs_logo_white.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -92,18 +92,15 @@ def find_version(*file_paths):
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 html_theme_options = {
-    "font_family": '"Avenir Next", Calibri, "PT Sans", sans-serif',
-    "head_font_family": '"Avenir Next", Calibri, "PT Sans", sans-serif',
-    "font_size": "18px",
-    "page_width": "980px",
-    "show_relbars": True,
+    "canonical_url": "https://www.attrs.org/",
+    "logo_only": True,
 }
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "_static/attrs_logo.svg"
+html_logo = "_static/attrs_logo_white.png"
 
 # 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
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,7 +6,7 @@ Release v\ |release| (`What's new? <changelog>`).
 
 .. include:: ../README.rst
    :start-after: teaser-begin
-   :end-before: -spiel-end-
+   :end-before: teaser-end
 
 
 Getting Started
@@ -17,7 +17,7 @@ The recommended installation method is `pip <https://pip.pypa.io/en/stable/>`_-i
 
 .. code-block:: console
 
-   $ pip install attrs
+   $ python -m pip install attrs
 
 The next three steps should bring you up and running in no time:
 
@@ -49,20 +49,8 @@ Day-to-Day Usage
 
 
 .. include:: ../README.rst
-   :start-after: -testimonials-
-   :end-before: -end-
-
-.. include:: ../README.rst
-   :start-after: -project-information-
-
-.. toctree::
-   :maxdepth: 1
-
-   license
-   backward-compatibility
-   python-2
-   contributing
-   changelog
+   :start-after: -getting-help-
+   :end-before: -project-information-
 
 
 ----
@@ -86,6 +74,19 @@ Full Table of Contents
    glossary
 
 
+.. include:: ../README.rst
+   :start-after: -project-information-
+
+.. toctree::
+   :maxdepth: 1
+
+   license
+   backward-compatibility
+   python-2
+   contributing
+   changelog
+
+
 Indices and tables
 ==================
 
diff --git a/docs/overview.rst b/docs/overview.rst
@@ -6,7 +6,7 @@ In order to fulfill its ambitious goal of bringing back the joy to writing class
 
 .. include:: ../README.rst
    :start-after: -code-begin-
-   :end-before: -testimonials-
+   :end-before: -getting-help-
 
 
 .. _philosophy:
diff --git a/setup.py b/setup.py
@@ -36,7 +36,7 @@
 ]
 INSTALL_REQUIRES = []
 EXTRAS_REQUIRE = {
-    "docs": ["sphinx", "zope.interface"],
+    "docs": ["sphinx", "sphinx-rtd-theme", "zope.interface"],
     "tests": [
         # 5.0 introduced toml; parallel was broken until 5.0.2
         "coverage[toml]>=5.0.2",
diff --git a/src/attr/_make.py b/src/attr/_make.py
@@ -134,8 +134,8 @@ def attrib(
 
     :type default: Any value
 
-    :param callable factory: Syntactic sugar for
-        ``default=attr.Factory(callable)``.
+    :param factory: Syntactic sugar for ``default=attr.Factory(callable)``.
+    :type factory: `callable`
 
     :param validator: `callable` that is called by ``attrs``-generated
         ``__init__`` methods after the instance has been initialized.  They
@@ -145,15 +145,15 @@ def attrib(
         The return value is *not* inspected so the validator has to throw an
         exception itself.
 
-        If a ``list`` is passed, its items are treated as validators and must
+        If a `list` is passed, its items are treated as validators and must
         all pass.
 
         Validators can be globally disabled and re-enabled using
         `get_run_validators`.
 
         The validator can also be set using decorator notation as shown below.
 
-    :type validator: ``callable`` or a ``list`` of ``callable``\\ s.
+    :type validator: `callable` or a `list` of `callable`\\ s.
 
     :param repr: Include this attribute in the generated ``__repr__``
         method. If ``True``, include the attribute; if ``False``, omit it. By
@@ -162,7 +162,7 @@ def attrib(
         value and returns a string. Note that the resulting string is used
         as-is, i.e. it will be used directly *instead* of calling ``repr()``
         (the default).
-    :type repr: a ``bool`` or a ``callable`` to use a custom function.
+    :type repr: a `bool` or a `callable` to use a custom function.
     :param bool eq: If ``True`` (default), include this attribute in the
         generated ``__eq__`` and ``__ne__`` methods that check two instances
         for equality.
@@ -174,16 +174,17 @@ def attrib(
         method.  If ``None`` (default), mirror *eq*'s value.  This is the
         correct behavior according the Python spec.  Setting this value to
         anything else than ``None`` is *discouraged*.
-    :type hash: ``bool`` or ``None``
+    :type hash: `bool` or `None`
     :param bool init: Include this attribute in the generated ``__init__``
         method.  It is possible to set this to ``False`` and set a default
         value.  In that case this attributed is unconditionally initialized
         with the specified default value or factory.
-    :param callable converter: `callable` that is called by
+    :param converter: `callable` that is called by
         ``attrs``-generated ``__init__`` methods to convert attribute's value
         to the desired format.  It is given the passed-in value, and the
         returned value will be used as the new value of the attribute.  The
         value is converted before being passed to the validator, if any.
+    :type converter: `callable`
     :param metadata: An arbitrary mapping, to be used by third-party
         components.  See `extending_metadata`.
     :param type: The type of the attribute.  In Python 3.6 or greater, the
@@ -856,7 +857,7 @@ def attrs(
         `object.__hash__`, and the `GitHub issue that led to the default \
         behavior <https://github.com/python-attrs/attrs/issues/136>`_ for more
         details.
-    :type hash: ``bool`` or ``None``
+    :type hash: `bool` or `None`
     :param bool init: Create a ``__init__`` method that initializes the
         ``attrs`` attributes.  Leading underscores are stripped for the
         argument name.  If a ``__attrs_post_init__`` method exists on the

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@`
`36`	`36`	`]`
`37`	`37`	`INSTALL_REQUIRES = []`
`38`	`38`	`EXTRAS_REQUIRE = {`
`39`		`- "docs": ["sphinx", "zope.interface"],`
	`39`	`+ "docs": ["sphinx", "sphinx-rtd-theme", "zope.interface"],`
`40`	`40`	`"tests": [`
`41`	`41`	`# 5.0 introduced toml; parallel was broken until 5.0.2`
`42`	`42`	`"coverage[toml]>=5.0.2",`