mkdocs-material/docs/bug-report/reproduction.md

110 lines
3.4 KiB
Markdown
Raw Normal View History

2023-01-01 21:08:42 +03:00
# Creating a reproduction
A reproduction is a simplified version of a bug that demonstrates the specific
scenario in which the bug occurred. It includes all necessary minimal settings
2023-01-02 16:03:01 +03:00
and instructions and should be as simple as possible while still demonstrating
2023-01-01 21:08:42 +03:00
the issue.
## Guide
### Environment <small>optional</small> { #environment }
We recommend using a [virtual environment], which is an isolated Python runtime.
If you are in a virtual environment, any packages that you install or upgrade
will be local to the environment. If you run into problems, you can
2023-01-02 16:03:01 +03:00
just delete and recreate the environment. It's trivial to set up:
2023-01-01 21:08:42 +03:00
- Create a new virtual environment with:
```
python3 -m venv venv
```
- Activate the environment with:
``` sh
. venv/bin/activate # (1)!
```
1. Your terminal should now print `(venv)` before the prompt, which is
how you know that you are inside an environment.
- Exit the environment with:
```
deactivate
```
[virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
### Minimal reproduction
2023-01-02 16:03:01 +03:00
Following the instructions below, you will set up a skeleton project to create
a reproduction. As mentioned above, we recommend using a [virtual environment],
so create a new folder in your working directory and a a new virtual environment
inside it. Next:
2023-01-01 21:08:42 +03:00
1. As mentioned in our [bug reporting guide], ensure that you're running the
2023-01-02 16:03:01 +03:00
latest version of Material for MkDocs, which might already include a fix for
2023-01-01 21:08:42 +03:00
the bug:
```
pip install --upgrade --force-reinstall mkdocs-material
```
2023-01-02 16:03:01 +03:00
2. Bootstrap a new documentation project using the `mkdocs` executable,
2023-01-01 21:08:42 +03:00
which you use as a basis for the reproduction. It's essential to create a
new, empty project for this:
```
mkdocs new .
```
2023-01-02 16:03:01 +03:00
Start by adding the [minimal configuration] in `mkdocs.yml`:
2023-01-01 21:08:42 +03:00
``` yaml
theme:
name: material
```
2023-01-02 16:03:01 +03:00
3. Now, only add the necessary settings to `mkdocs.yml` to keep the
2023-01-01 21:08:42 +03:00
reproduction minimal. If you are creating a reproduction for a rendering
bug, create only the necessary amount of Markdown documents. __Repeat this
step until the bug you want to report can be observed.__
2023-01-02 16:03:01 +03:00
4. As a last step, before packing everything into a .zip file, double-check
all settings and documents if they are essential to the reproduction, which
2023-01-01 21:08:42 +03:00
means that the bug does not occur when they are omitted. Remove all
non-essential lines and files.
[bug reporting guide]: index.md#upgrade-to-latest-version
[minimal configuration]: ../../creating-your-site/#minimal-configuration
### Creating a .zip file
2023-01-02 16:03:01 +03:00
Material for MkDocs 9.0.0 includes a new plugin solely intended to create
2023-01-01 21:08:42 +03:00
reproductions for bug reports. When the built-in info plugin is enabled, MkDocs
2023-01-02 16:03:01 +03:00
will add all relevant files to a .zip, print a summary to the terminal and
2023-01-01 21:08:42 +03:00
exit. Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- info
```
Now, when running `mkdocs build`, a file called `example.zip` is automatically
2023-01-02 16:03:01 +03:00
created, containing the minimal reproduction you can directly attach to your bug
2023-01-01 21:08:42 +03:00
report.
```
INFO - Started archive creation for bug report
INFO - Archive successfully created:
example/.dependencies.json 859.0 B
example/.versions.log 83.0 B
example/docs/index.md 282.0 B
example/mkdocs.yml 56.0 B
example.zip 1.8 kB
```