Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[2492] Add new page to document installation methods #3941

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

[2492] Add new page to document installation methods #3941

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a1bb176
[2492] Add new page to document installation methods
takoman-mg Oct 12, 2023
d61e37a
[2492] Additions based on PR comments
takoman-mg Oct 16, 2023
919a44b
[2492] Added MyST substitution extension and code
takoman-mg Oct 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/getting_started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ If you can't wait for the latest _hotness_ and want to install from GitHub, use:

`pip install git+https://github.com/psf/black`

For more ways to install _Black_, check
[Ways to install Black](./usage_and_configuration/ways_to_install_black.md)

## Basic usage

To get started right away with sensible defaults:
Expand Down
5 changes: 4 additions & 1 deletion docs/usage_and_configuration/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
hidden:
---

ways_to_install_black
the_basics
file_collection_and_discovery
black_as_a_server
Expand All @@ -20,8 +21,10 @@ purposefully limited.
Using many of these more advanced features of _Black_ will require some configuration.
Configuration that will either live on the command line or in a TOML configuration file.

This section covers features of _Black_ and configuring _Black_ in detail:
This section covers installation methods, features of _Black_, and configuring _Black_
in detail:

- {doc}`Ways to install Black <./ways_to_install_black>`
- {doc}`The basics <./the_basics>`
- {doc}`File collection and discovery <file_collection_and_discovery>`
- {doc}`Black as a server (blackd) <./black_as_a_server>`
Expand Down
46 changes: 46 additions & 0 deletions docs/usage_and_configuration/ways_to_install_black.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Ways to install Black

There are several ways you can install _Black_.

## Install from PyPI

To install the latest release of _Black_ from [PyPI] (Requires Python 3.8+), use:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we can link to the pyproject.toml directive here to avoid having yet another place to upgrade when we move to requiring >= 3.9 - All for ideas here but can live with it if it's to hard ...

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm checking if this can be done via tomli and Sphinx configuration somehow.


`pip install black`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

O - Just thought of it - Please talk about all black's optional installs in this section too, please.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added, please check!


A _Black_ release currently offers three types of artifacts via PyPI, as outlined in the
[Release Process]:

1. The source distribution of the release
2. Generic Python wheel, meant for use on any Python supported platform
3. Platform and Python version specific wheels that offer significantly improved
performance, compiled using [mypyc]

By default, `pip` will prefer a compatible wheel and revert to the source distribution
if no such wheels are found, as outlined in [Python documentation].
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
if no such wheels are found, as outlined in [Python documentation].
if no such wheels are found, as outlined in [Python documentation](LINK).

Did you forget the link?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The links were all declared at the end of the page, similar to other pages in the documentation. I've changed all of them to avoid confusion.


## Install from GitHub

To install the latest version of _Black_ from GitHub, use:

`pip install git+https://github.com/psf/black`
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To install the latest version of _Black_ from GitHub, use:
`pip install git+https://github.com/psf/black`
To install the latest version of _Black_ from GitHub, use:
`pip install git+https://github.com/psf/black`
- This will install from the latest commit from `main` branch

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.


## Get native binaries from GitHub

[GitHub Releases] for _Black_ contain self-contained, native binaries for multiple
platforms (built using PyInstaller). This allows you to download the executable for your
platform and run _Black_ without a Python runtime installed.

## Black Docker images

Official _Black_ Docker images are available on [Docker Hub]. For more information,
check the [Black Docker image] section.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Official _Black_ Docker images are available on [Docker Hub]. For more information,
check the [Black Docker image] section.
Official _Black_ Docker images are available on [Docker Hub](https://hub.docker.com/r/pyfound/black). For more information,
check the [Black Docker image](LINK_TO_PAGE) page.
- `docker run --rm --volume $(pwd):/src --workdir /src pyfound/black:latest_release black --check .`

Command example optional but I think we should fix the link to make this page more useful.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left out the command example because it's already present in the Black Docker page, can add it if required.


[PyPI]: https://pypi.org/project/black/
[Release Process]: ./../contributing/release_process
[mypyc]: https://mypyc.readthedocs.io/
[Python documentation]:
https://packaging.python.org/en/latest/tutorials/installing-packages/#source-distributions-vs-wheels
[GitHub Releases]: https://github.com/psf/black/releases
[Docker Hub]: https://hub.docker.com/r/pyfound/black
[Black Docker image]: ./black_docker_image