diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 585e84ba2d..1dec15ba1d 100644 --- a/CHANGELOG.txt +++ b/CHANGELOG.txt @@ -20,6 +20,7 @@ Changelog * Docs: Add code block to make it easier to understand contribution docs (Suyash Singh) * Docs: Add new "Icons" page for icons customisation and reuse across the admin interface (Coen van der Kamp) * Docs: Fix broken formatting for MultiFieldPanel / FieldRowPanel permission kwarg docs (Matt Westcott) + * Docs: Add helpful troubleshooting links and refine wording for getting started with development (Loveth Omokaro) * Maintenance: Removed features deprecated in Wagtail 3.0 and 4.0 (Matt Westcott) * Maintenance: Update djhtml (html formatting) library to v 1.5.2 (Loveth Omokaro) * Maintenance: Re-enable `strictPropertyInitialization` in tsconfig (Thibaud Colas) diff --git a/docs/contributing/developing.md b/docs/contributing/developing.md index 47cd6179c7..45bf75bde2 100644 --- a/docs/contributing/developing.md +++ b/docs/contributing/developing.md @@ -19,14 +19,14 @@ Alternatively, you can install [Node.js](https://nodejs.org/) directly, ensure y You will also need to install the **libjpeg** and **zlib** libraries, if you haven't done so already - see Pillow's [platform-specific installation instructions](https://pillow.readthedocs.io/en/stable/installation.html#external-libraries). -Clone a copy of [the Wagtail codebase](https://github.com/wagtail/wagtail): +Fork the [the Wagtail codebase](https://github.com/wagtail/wagtail) and clone the forked copy: ```sh -git clone https://github.com/wagtail/wagtail.git +git clone https://github.com/username/wagtail/wagtail.git cd wagtail ``` -**With your preferred virtualenv activated,** install the Wagtail package in development mode with the included testing and documentation dependencies: +**With your preferred [virtualenv activated](virtual_environment_creation),** install the Wagtail package in development mode with the included testing and documentation dependencies: ```sh pip install -e ."[testing,docs]" -U diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index 06c37ca45a..b386f4d41c 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -13,7 +13,7 @@ ## Dependencies needed for installation -- [Python 3](https://www.python.org/downloads/) +- [Python 3](https://www.python.org/downloads/). - **libjpeg** and **zlib**, libraries required for Django's **Pillow** library. See Pillow's [platform-specific installation instructions](https://pillow.readthedocs.io/en/stable/installation.html#external-libraries). @@ -65,3 +65,25 @@ demo_site integrating_into_django the_zen_of_wagtail ``` + +(common_installation_issues)= + +## Common issues + +### Python is not available in `path` + +```sh +python +> command not found: python +``` + +For detailed guidance, see this guide on [how to add Python to your path](https://realpython.com/add-python-to-path/). + +### python3 not available + +```sh +python3 -m pip install --upgrade pip +> command not found: python3 +``` + +If this error occurs, [the `python3` can be replaced with `py`](https://docs.python.org/3/faq/windows.html#how-do-i-run-a-python-program-under-windows). diff --git a/docs/getting_started/tutorial.md b/docs/getting_started/tutorial.md index 986105bbc6..9c02c5fbdf 100644 --- a/docs/getting_started/tutorial.md +++ b/docs/getting_started/tutorial.md @@ -31,6 +31,8 @@ The way to do this varies by platform—see Pillow's [platform-specific installation instructions](https://pillow.readthedocs.io/en/stable/installation.html#external-libraries). ``` +(virtual_environment_creation)= + ### Create and activate a virtual environment We recommend using a virtual environment, which isolates installed dependencies from other projects. diff --git a/docs/releases/5.0.md b/docs/releases/5.0.md index a5aeda91ad..20b8ef9e43 100644 --- a/docs/releases/5.0.md +++ b/docs/releases/5.0.md @@ -36,6 +36,7 @@ depth: 1 * Add code block to make it easier to understand contribution docs (Suyash Singh) * Add new "Icons" page for icons customisation and reuse across the admin interface (Coen van der Kamp) * Fix broken formatting for MultiFieldPanel / FieldRowPanel permission kwarg docs (Matt Westcott) + * Add helpful troubleshooting links and refine wording for getting started with development (Loveth Omokaro) ### Maintenance