From 7f37a31297e6917479a025c8f601407ee9e4ad03 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 3 May 2020 19:48:25 +0200 Subject: [PATCH 1/8] remove the version pinning for black in requirements.txt --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 171be42..da1b2c5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -black==19.10b0 +black flake8 more-itertools pytest From c1741cddc9964977dec5e43c01604d06e2a60d54 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 3 May 2020 19:58:19 +0200 Subject: [PATCH 2/8] add install instructions --- README.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/README.rst b/README.rst index 3d296c9..c0b5719 100644 --- a/README.rst +++ b/README.rst @@ -14,6 +14,20 @@ It was originally a rewrite of a `gist`_ and called .. _gist: https://gist.github.com/mattharrison/2a1a263597d80e99cf85e898b800ec32 .. _black: https://github.com/psf/black +Installation +------------ +Dependencies: +- `black`_ +- `more-itertools`_ + +.. _more-itertools: https://github.com/more-itertools/more-itertools + +Install it with: + +.. code:: bash + + python -m pip install blackdoc + Usage ----- The commandline interface supports two modes: checking and inplace From ac0b26c0cf5abb4babeda5b3ca0ceae656775e74 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 3 May 2020 20:51:16 +0200 Subject: [PATCH 3/8] fix the dependency list --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index c0b5719..aa985ed 100644 --- a/README.rst +++ b/README.rst @@ -17,6 +17,7 @@ It was originally a rewrite of a `gist`_ and called Installation ------------ Dependencies: + - `black`_ - `more-itertools`_ From addfe86ef2a75138fecabcc859ab1bb1dd0e63de Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 3 May 2020 23:52:51 +0200 Subject: [PATCH 4/8] mention the console script --- README.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.rst b/README.rst index aa985ed..b5f8786 100644 --- a/README.rst +++ b/README.rst @@ -55,3 +55,9 @@ When checking, it will report the changed files but will not write them to disk: .. code:: bash python -m blackdoc --check . + +It is also possible to use the entrypoint script: + +.. code:: bash + + blackdoc --check . From bd97ecd23853f1bec429c3a31197b92525792db1 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sun, 3 May 2020 23:53:22 +0200 Subject: [PATCH 5/8] show help --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index b5f8786..0150b41 100644 --- a/README.rst +++ b/README.rst @@ -60,4 +60,4 @@ It is also possible to use the entrypoint script: .. code:: bash - blackdoc --check . + blackdoc --help From e7e973e06f6b8055b768a285710675cbb797d530 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 30 May 2020 22:58:27 +0200 Subject: [PATCH 6/8] update the install instructions --- doc/index.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 8b44a31..81a5078 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -19,13 +19,11 @@ Its dependencies are: - `importlib-metadata`_ (on **python** < 3.8) -It has not been released, yet, so use: +To install it, use .. code:: bash - python -m pip install git+https://github.com/keewis/blackdoc - -for installing. + python -m pip install blackdoc .. _more-itertools: https://more-itertools.readthedocs.io/ From a448ff4e403869540b9f39ae0cb144d38825c4d4 Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 30 May 2020 23:23:03 +0200 Subject: [PATCH 7/8] split the documentation into several files --- doc/index.rst | 86 +++------------------------------------------- doc/installing.rst | 19 ++++++++++ doc/usage.rst | 62 +++++++++++++++++++++++++++++++++ 3 files changed, 86 insertions(+), 81 deletions(-) create mode 100644 doc/installing.rst create mode 100644 doc/usage.rst diff --git a/doc/index.rst b/doc/index.rst index 81a5078..87052d0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,86 +10,10 @@ The currently supported formats are: - ipython - rst -Installation ------------- -Its dependencies are: -- `black`_ -- `more-itertools`_ -- `importlib-metadata`_ (on **python** < 3.8) +.. toctree:: + :maxdepth: 1 + :caption: Contents - -To install it, use - -.. code:: bash - - python -m pip install blackdoc - - -.. _more-itertools: https://more-itertools.readthedocs.io/ -.. _black: https://black.readthedocs.io/en/stable/ -.. _importlib-metadata: https://importlib-metadata.readthedocs.io/en/latest/ - - -Usage ------ -**blackdoc** tries to copy as much of the CLI of **black** as -possible. This means that most calls to **black** can be directly -translated to **blackdoc**: - -To reformat specific files, use: - -.. code:: sh - - python -m blackdoc file1 file2 ... - -while passing directories reformats all files in those directories -that match the file format specified by ``--include`` and -``--exclude``: - -.. code:: sh - - python -m blackdoc directory1 directory2 ... - -mixing directories and files is also possible. - -As an example, having a structure like:: - - directory - ├── file.py - └── file.rst - -with - -.. literalinclude:: directory/file.py - -.. literalinclude:: directory/file.rst - :language: rst - -If we run - -.. code:: sh - - python -m blackdoc directory - -we get - -.. literalinclude:: directory/reformatted.py - -.. literalinclude:: directory/reformatted.rst - :language: rst - -If instead we run - -.. code:: sh - - python -m blackdoc --check directory - -the result is:: - - would reformat directory/file.rst - would reformat directory/file.py - Oh no! 💥 💔 💥 - 2 files would be reformatted. - -with a non-zero exit status. + installing + usage diff --git a/doc/installing.rst b/doc/installing.rst new file mode 100644 index 0000000..74edbdc --- /dev/null +++ b/doc/installing.rst @@ -0,0 +1,19 @@ +Installation +------------ +Its dependencies are: + +- `black`_ +- `more-itertools`_ +- `importlib-metadata`_ (on **python** < 3.8) + + +To install it, use + +.. code:: bash + + python -m pip install blackdoc + + +.. _more-itertools: https://more-itertools.readthedocs.io/ +.. _black: https://black.readthedocs.io/en/stable/ +.. _importlib-metadata: https://importlib-metadata.readthedocs.io/en/latest/ diff --git a/doc/usage.rst b/doc/usage.rst new file mode 100644 index 0000000..ad0dc0a --- /dev/null +++ b/doc/usage.rst @@ -0,0 +1,62 @@ +Usage +----- +**blackdoc** tries to copy as much of the CLI of **black** as +possible. This means that most calls to **black** can be directly +translated to **blackdoc**: + +To reformat specific files, use: + +.. code:: sh + + python -m blackdoc file1 file2 ... + +while passing directories reformats all files in those directories +that match the file format specified by ``--include`` and +``--exclude``: + +.. code:: sh + + python -m blackdoc directory1 directory2 ... + +mixing directories and files is also possible. + +As an example, having a structure like:: + + directory + ├── file.py + └── file.rst + +with + +.. literalinclude:: directory/file.py + +.. literalinclude:: directory/file.rst + :language: rst + +If we run + +.. code:: sh + + python -m blackdoc directory + +we get + +.. literalinclude:: directory/reformatted.py + +.. literalinclude:: directory/reformatted.rst + :language: rst + +If instead we run + +.. code:: sh + + python -m blackdoc --check directory + +the result is:: + + would reformat directory/file.rst + would reformat directory/file.py + Oh no! 💥 💔 💥 + 2 files would be reformatted. + +with a non-zero exit status. From a6071f43e575f698ef503ef5f14286b17e02953d Mon Sep 17 00:00:00 2001 From: Keewis Date: Sat, 30 May 2020 23:23:28 +0200 Subject: [PATCH 8/8] add a crude changelog --- doc/changelog.rst | 11 +++++++++++ doc/index.rst | 1 + 2 files changed, 12 insertions(+) create mode 100644 doc/changelog.rst diff --git a/doc/changelog.rst b/doc/changelog.rst new file mode 100644 index 0000000..fed0615 --- /dev/null +++ b/doc/changelog.rst @@ -0,0 +1,11 @@ +Changelog +========= + +v0.1 (unreleased) +----------------- + +- Add a CLI (:pull:`1`) +- Add support for ipython prompts (:pull:`4`) +- Add support for code blocks in rst files (:pull:`10`) +- Allow disabling / selectively enabling formats (:issue:`13`, :pull:`18`) +- Initial version of the documentation (:issue:`12`, :pull:`19`) diff --git a/doc/index.rst b/doc/index.rst index 87052d0..5e9203d 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -17,3 +17,4 @@ The currently supported formats are: installing usage + changelog