Documentation fixes for ReadTheDocs

psf · Mar 25, 2018 · 9e31754 · 9e31754
1 parent 0677a53
commit 9e31754
Show file tree

Hide file tree

Showing 11 changed files with 175 additions and 61 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,7 +10,7 @@ In terms of inspiration, *Black* is about as configurable as *gofmt* and
 *rustfmt* are.  This is deliberate.
 
 Bug reports and fixes are always welcome!  Please follow the issue
-template for best results.
+template on GitHub for best results.
 
 Before you suggest a new feature or configuration knob, ask yourself why
 you want it.  If it enables better integration with some workflow, fixes

diff --git a/Pipfile b/Pipfile
@@ -14,4 +14,6 @@ flake8 = "*"
 flake8-bugbear = "*"
 flake8-mypy = "*"
 mypy = "*"
+recommonmark = "*"
+Sphinx = "*"
 twine = ">=1.11.0rc1"
diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/README.md b/README.md
@@ -34,9 +34,16 @@ original.  This slows it down.  If you're feeling confident, use
 ``--fast``.
 
 
+## Installation
+
+*Black* can be installed by running `pip install black`.  It requires
+Python 3.6.0+ to run but you can reformat Python 2 code with it, too.
+*Black* is able to parse all of the new syntax supported on Python 3.6
+but also *effectively all* the Python 2 syntax at the same time.
+
+
 ## Usage
 
-*Black* can be installed by running `pip install black`.
 
 ```
 black [OPTIONS] [SRC]...
@@ -262,27 +269,6 @@ Use the badge in your project's README.md:
 Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 
-
-## Tests
-
-Just run:
-
-```
-python setup.py test
-```
-
-## This tool requires Python 3.6.0+ to run
-
-But you can reformat Python 2 code with it, too.  *Black* is able to parse
-all of the new syntax supported on Python 3.6 but also *effectively all*
-the Python 2 syntax at the same time.
-
-By making the code exclusively Python 3.6+, I'm able to focus on the
-quality of the formatting and re-use all the nice features of the new
-releases (check out [pathlib](https://docs.python.org/3/library/pathlib.html) or
-f-strings) instead of wasting cycles on Unicode compatibility, and so on.
-
-
 ## License
 
 MIT
@@ -402,3 +388,6 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 ## Authors
 
 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
+
+[Model T logo](https://thenounproject.com/term/model-t/16785/) by Alex
+Valdivia from the Noun Project.
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
diff --git a/docs/_static/logo2.png b/docs/_static/logo2.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,7 +15,7 @@
 import os
 import sys
 
-import recommonmark
+from recommonmark.parser import CommonMarkParser
 
 
 sys.path.insert(0, os.path.abspath('.' ))
@@ -52,7 +52,7 @@
 templates_path = ['_templates']
 
 source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
+    '.md': CommonMarkParser,
 }
 
 # The suffix(es) of source filenames.
@@ -97,12 +97,14 @@
 
 html_theme_options = {
     'show_related': True,
-    'description': 'The uncompromising Python code formatter',
+    'description': '“Any color you like.”',
+    'github_button': True,
     'github_user': 'ambv',
     'github_repo': 'black',
-    'github_button': True,
+    'github_type': 'star',
     'show_powered_by': True,
     'fixed_sidebar': True,
+    'logo': 'logo2.png',
 }
 
 
@@ -162,7 +164,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'black', 'Documentation for black',
+    (master_doc, 'black', 'Documentation for Black',
      [author], 1)
 ]
 
@@ -205,4 +207,4 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3/': None}
+intersphinx_mapping = {'https://docs.python.org/3/': None}
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
diff --git a/docs/contributors_guide.md b/docs/contributors_guide.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,16 +1,13 @@
 .. black documentation master file, created by
    sphinx-quickstart on Fri Mar 23 10:53:30 2018.
 
-Black
-=====
+The uncompromising code formatter
+=================================
 
-**Black** is the uncompromising Python code formatter. 
-
-By using *Black*, you
-agree to cease control over minutiae of hand-formatting. In return,
-*Black* gives you speed, determinism, and freedom from `pycodestyle`
-nagging about formatting. You will save time and mental energy for
-more important matters.
+By using *Black*, you agree to cease control over minutiae of
+hand-formatting. In return, *Black* gives you speed, determinism, and
+freedom from `pycodestyle` nagging about formatting. You will save time
+and mental energy for more important matters.
 
 *Black* makes code review faster by producing the smallest diffs
 possible. Blackened code looks the same regardless of the project
@@ -19,7 +16,7 @@ can focus on the content instead.
 
 .. note::
 
-   Black is an early pre-release.
+   `Black is an early pre-release <usage.html#note-this-tool-is-alpha-quality-at-the-moment>`_.
 
 
 Testimonials
@@ -51,9 +48,9 @@ Contents
 
    usage
    technical_philosophy
-   contributors_guide
+   contributing
    changelog
-   
+
 
 Indices and tables
 ==================