Documentation fixes for ReadTheDocs

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 596ce73565f1468668f988ff986575b79482e2d7..4c94ea726fae207aeac948a73b478292fbcb5a93 100644 (file)
--- 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
index deb40c95f7459831947def9dce63e27faaf8ae68..bcd8c8aeffed5e1b8f8792efaaf5f6c473d58a6f 100644 (file)
--- 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
index caf8bcab81165392368d6d98cb78a0948475bb8c..68010ab83f1a00c407bd6462c8c9bc21c7ad4331 100644 (file)
--- a/Pipfile.lock
+++ b/Pipfile.lock
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "60c8cea641a1b59665d84ef4905ff25013ff9ec899630d60066db0981c4c7e3b"
+            "sha256": "51d523fcd093fbf1fd034cd7ad0be9d34dc0fead60b2e23558b4a54f5c0c0ef6"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -32,6 +32,13 @@
         }
     },
     "develop": {
+        "alabaster": {
+            "hashes": [
+                "sha256:2eef172f44e8d301d25aff8068fddd65f767a3f04b5f15b0f4922f113aa1c732",
+                "sha256:37cdcb9e9954ed60912ebc1ca12a9d12178c26637abdf124e3cde2341c257fe0"
+            ],
+            "version": "==0.7.10"
+        },
         "attrs": {
             "hashes": [
                 "sha256:1c7960ccfd6a005cd9f7ba884e6316b5e430a3f1a6c37c5f87d8b43f83b54ec9",
@@ -40,6 +47,13 @@
             "index": "pypi",
             "version": "==17.4.0"
         },
+        "babel": {
+            "hashes": [
+                "sha256:8ce4cb6fdd4393edd323227cba3a077bceb2a6ce5201c902c65e730046f41f14",
+                "sha256:ad209a68d7162c4cff4b29cdebe3dec4cef75492df501b0049a9433c96ce6f80"
+            ],
+            "version": "==2.5.3"
+        },
         "certifi": {
             "hashes": [
                 "sha256:14131608ad2fd56836d33a71ee60fa1c82bc9d2c8d98b7bdbc631fe1b3cd1296",
@@ -54,6 +68,12 @@
             ],
             "version": "==3.0.4"
         },
+        "commonmark": {
+            "hashes": [
+                "sha256:34d73ec8085923c023930dfc0bcd1c4286e28a2a82de094bb72fabcc0281cbe5"
+            ],
+            "version": "==0.5.4"
+        },
         "coverage": {
             "hashes": [
                 "sha256:03481e81d558d30d230bc12999e3edffe392d244349a90f4ef9b88425fac74ba",
@@ -96,6 +116,14 @@
             "index": "pypi",
             "version": "==4.5.1"
         },
+        "docutils": {
+            "hashes": [
+                "sha256:02aec4bd92ab067f6ff27a38a38a41173bf01bed8f89157768c1573f53e474a6",
+                "sha256:51e64ef2ebfb29cae1faa133b3710143496eca21c530f3f71424d77687764274",
+                "sha256:7a4bd47eaf6596e1295ecb11361139febe29b084a87bf005bf899f9a42edc3c6"
+            ],
+            "version": "==0.14"
+        },
         "flake8": {
             "hashes": [
                 "sha256:7253265f7abd8b313e3892944044a365e3f4ac3fcdcfb4298f55ee9ddf188ba0",
@@ -127,6 +155,26 @@
             ],
             "version": "==2.6"
         },
+        "imagesize": {
+            "hashes": [
+                "sha256:3620cc0cadba3f7475f9940d22431fc4d407269f1be59ec9b8edcca26440cf18",
+                "sha256:5b326e4678b6925158ccc66a9fa3122b6106d7c876ee32d7de6ce59385b96315"
+            ],
+            "version": "==1.0.0"
+        },
+        "jinja2": {
+            "hashes": [
+                "sha256:74c935a1b8bb9a3947c50a54766a969d4846290e1e788ea44c1392163723c3bd",
+                "sha256:f84be1bb0040caca4cea721fcbbbbd61f9be9464ca236387158b0feea01914a4"
+            ],
+            "version": "==2.10"
+        },
+        "markupsafe": {
+            "hashes": [
+                "sha256:a6be69091dac236ea9c6bc7d012beab42010fa914c459791d627dad4910eb665"
+            ],
+            "version": "==1.0"
+        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
@@ -136,11 +184,18 @@
         },
         "mypy": {
             "hashes": [
-                "sha256:83d798f66323f2de6191d66d9ae5ab234e4ee5b400010e19c58d75d308049f25",
-                "sha256:884f18f3a40cfcf24cdd5860b84958cfb35e6563e439c5adc1503878df221dc3"
+                "sha256:3bd95a1369810f7693366911d85be9f0a0bd994f6cb7162b7a994e5ded90e3d9",
+                "sha256:7247f9948d7cdaae9408a4ee1662a01853c24e668117b4419acf025b05fbe3ce"
             ],
             "index": "pypi",
-            "version": "==0.570"
+            "version": "==0.580"
+        },
+        "packaging": {
+            "hashes": [
+                "sha256:e9215d2d2535d3ae866c3d6efc77d5b24a0192cce0ff20e42896cc0664f889c0",
+                "sha256:f019b770dd64e585a99714f1fd5e01c7a8f11b45635aa953fd41c689a657375b"
+            ],
+            "version": "==17.1"
         },
         "pkginfo": {
             "hashes": [
@@ -163,6 +218,47 @@
             ],
             "version": "==1.6.0"
         },
+        "pygments": {
+            "hashes": [
+                "sha256:78f3f434bcc5d6ee09020f92ba487f95ba50f1e3ef83ae96b9d5ffa1bab25c5d",
+                "sha256:dbae1046def0efb574852fab9e90209b23f556367b5a320c0bcb871c77c3e8cc"
+            ],
+            "version": "==2.2.0"
+        },
+        "pyparsing": {
+            "hashes": [
+                "sha256:0832bcf47acd283788593e7a0f542407bd9550a55a8a8435214a1960e04bcb04",
+                "sha256:281683241b25fe9b80ec9d66017485f6deff1af5cde372469134b56ca8447a07",
+                "sha256:8f1e18d3fd36c6795bb7e02a39fd05c611ffc2596c1e0d995d34d67630426c18",
+                "sha256:9e8143a3e15c13713506886badd96ca4b579a87fbdf49e550dbfc057d6cb218e",
+                "sha256:b8b3117ed9bdf45e14dcc89345ce638ec7e0e29b2b579fa1ecf32ce45ebac8a5",
+                "sha256:e4d45427c6e20a59bf4f88c639dcc03ce30d193112047f94012102f235853a58",
+                "sha256:fee43f17a9c4087e7ed1605bd6df994c6173c1e977d7ade7b651292fab2bd010"
+            ],
+            "version": "==2.2.0"
+        },
+        "pytz": {
+            "hashes": [
+                "sha256:07edfc3d4d2705a20a6e99d97f0c4b61c800b8232dc1c04d87e8554f130148dd",
+                "sha256:3a47ff71597f821cd84a162e71593004286e5be07a340fd462f0d33a760782b5",
+                "sha256:410bcd1d6409026fbaa65d9ed33bf6dd8b1e94a499e32168acfc7b332e4095c0",
+                "sha256:5bd55c744e6feaa4d599a6cbd8228b4f8f9ba96de2c38d56f08e534b3c9edf0d",
+                "sha256:61242a9abc626379574a166dc0e96a66cd7c3b27fc10868003fa210be4bff1c9",
+                "sha256:887ab5e5b32e4d0c86efddd3d055c1f363cbaa583beb8da5e22d2fa2f64d51ef",
+                "sha256:ba18e6a243b3625513d85239b3e49055a2f0318466e0b8a92b8fb8ca7ccdf55f",
+                "sha256:ed6509d9af298b7995d69a440e2822288f2eca1681b8cce37673dbb10091e5fe",
+                "sha256:f93ddcdd6342f94cea379c73cddb5724e0d6d0a1c91c9bdef364dc0368ba4fda"
+            ],
+            "version": "==2018.3"
+        },
+        "recommonmark": {
+            "hashes": [
+                "sha256:6e29c723abcf5533842376d87c4589e62923ecb6002a8e059eb608345ddaff9d",
+                "sha256:cd8bf902e469dae94d00367a8197fb7b81fcabc9cfb79d520e0d22d0fbeaa8b7"
+            ],
+            "index": "pypi",
+            "version": "==0.4.0"
+        },
         "requests": {
             "hashes": [
                 "sha256:6a1b267aa90cac58ac3a765d067950e7dbbf75b1da07e895d1f594193a40a38b",
@@ -177,6 +273,35 @@
             ],
             "version": "==0.8.0"
         },
+        "six": {
+            "hashes": [
+                "sha256:70e8a77beed4562e7f14fe23a786b54f6296e34344c23bc42f07b15018ff98e9",
+                "sha256:832dc0e10feb1aa2c68dcc57dbb658f1c7e65b9b61af69048abc87a2db00a0eb"
+            ],
+            "version": "==1.11.0"
+        },
+        "snowballstemmer": {
+            "hashes": [
+                "sha256:919f26a68b2c17a7634da993d91339e288964f93c274f1343e3bbbe2096e1128",
+                "sha256:9f3bcd3c401c3e862ec0ebe6d2c069ebc012ce142cce209c098ccb5b09136e89"
+            ],
+            "version": "==1.2.1"
+        },
+        "sphinx": {
+            "hashes": [
+                "sha256:5a1c9a0fec678c24b9a2f5afba240c04668edb7f45c67ce2ed008996b3f21ae2",
+                "sha256:7a606d77618a753adb79e13605166e3cf6a0e5678526e044236fc1ac43650910"
+            ],
+            "index": "pypi",
+            "version": "==1.7.2"
+        },
+        "sphinxcontrib-websupport": {
+            "hashes": [
+                "sha256:7a85961326aa3a400cd4ad3c816d70ed6f7c740acd7ce5d78cd0a67825072eb9",
+                "sha256:f4932e95869599b89bf4f80fc3989132d83c9faa5bf633e7b5e0c25dffb75da2"
+            ],
+            "version": "==1.0.1"
+        },
         "tqdm": {
             "hashes": [
                 "sha256:05e991ecb0f874046ddcb374396a626afd046fb4d31f73633ea752b844458a7a",

diff --git a/README.md b/README.md
index 6efc7e90b567cb74d0f4300b52c938cea4c325f9..d5c88f40d92ff03068693d83615dbace8bbd0db0 100644 (file)
--- 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
new file mode 100644 (file)
index 0000000..ba07615
Binary files /dev/null and b/docs/_static/logo.png differ

diff --git a/docs/_static/logo2.png b/docs/_static/logo2.png
new file mode 100644 (file)
index 0000000..388f93c
Binary files /dev/null and b/docs/_static/logo2.png differ

diff --git a/docs/conf.py b/docs/conf.py
index efb6359849a913acbd82c74e50df3b475c3ad710..4a3c67c81985b27b58edf4e42119966cb7f1a4d0 100644 (file)
--- 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 @@ extensions = [
 templates_path = ['_templates']
 
 source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
+    '.md': CommonMarkParser,
 }
 
 # The suffix(es) of source filenames.
@@ -97,12 +97,14 @@ html_sidebars = {
 
 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 @@ latex_documents = [
 # 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 @@ epub_exclude_files = ['search.html']
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3/': None}
\ No newline at end of file
+intersphinx_mapping = {'https://docs.python.org/3/': None}

diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 120000 (symlink)
index 0000000..44fcc63
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1 @@
+../CONTRIBUTING.md
\ No newline at end of file

diff --git a/docs/contributors_guide.md b/docs/contributors_guide.md
deleted file mode 100644 (file)
index 6b82bb4..0000000
--- a/docs/contributors_guide.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Contributors Guide
-
-## Tests
-
-Just run:
-
-```bash
-python setup.py test
-```
\ No newline at end of file

diff --git a/docs/index.rst b/docs/index.rst
index 0106c9cfdc8d555bfa494f25aff25b9a6be54f84..7a0995bb78136ebea5159c2bca6d91aed12448c5 100644 (file)
--- 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
 ==================

diff --git a/docs/usage.md b/docs/usage.md
index c27c74411d97894491c408c0c0d1e5e23b57c0bb..d90ca8845b3bb3da3ef20414f4ef2554cdb1b5ee 100644 (file)
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -2,28 +2,34 @@
 
 ## Installation
 
-*Black* can be installed by running `pip install black`.
+*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
 
 To get started right away with sensible defaults:
 
 ```
-black {source_file}
+black {source_file_or_directory}
 ```
 
+
 ### Command line options
 
-Some basics about the command line help, `black --help`:
+Black doesn't provide many options.  You can list them by running
+`black --help`:
 
-```
+```text
 Usage: black [OPTIONS] [SRC]...
 
   The uncompromising code formatter.
 
 Options:
-  -l, --line-length INTEGER  How many character per line to allow.  [default:
-                             88]
+  -l, --line-length INTEGER  How many character per line to allow.
+                             [default: 88]
   --check                    Don't write back the files, just return the
                              status.  Return code 0 means nothing would
                              change.  Return code 1 means some files would be
@@ -44,7 +50,8 @@ Options:
 * exits with code 0 unless an internal error occured (or `--check` was
   used).
 
-## Important note about the pre-release of Black
+
+## NOTE: This tool is alpha quality at the moment
 
 *Black* can already successfully format itself and the standard library.
 It also sports a decent test suite.  However, it is still very new.