centersl/mkdocs
1
0
Fork 0
mirror of https://github.com/mkdocs/mkdocs.git synced 2026-03-27 09:58:31 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update CONTRIBUTING.md

Browse Source
This commit is contained in:
Oleh Prypin
2023-12-10 14:00:09 +01:00
parent 9af473c71c
commit 09ff0ab247
2 changed files with 105 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
CONTRIBUTING.md
View File

@@ -2,7 +2,7 @@
An introduction to contributing to the MkDocs project.
The MkDocs project welcomes, and depends, on contributions from developers and
The MkDocs project welcomes contributions from developers and
users in the open source community. Contributions can be made in a number of
ways, a few examples are:
@@ -11,68 +11,126 @@ ways, a few examples are:
- Bug reports and patch reviews
For information about available communication channels please refer to the
[README](https://github.com/mkdocs/mkdocs/blob/master/README.md) file in our
[README](https://github.com/mkdocs/mkdocs#readme) file in our
GitHub repository.
## Code of Conduct
Everyone interacting in the MkDocs project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
## Reporting an Issue
Please include as much detail as you can. Let us know your platform and MkDocs
version. If the problem is visual (for example a theme or design issue) please
add a screenshot and if you get an error please include the full error and
version. If the problem is visual (for example a theme or design issue), please
add a screenshot. If you get an error, please include the full error message and
traceback.
## Testing the Development Version
It is particularly helpful if an issue report touches on all of these aspects:
1. What are you trying to achieve?
2. What is your `mkdocs.yml` configuration (+ other relevant files)? Preferably reduced to the minimal reproducible example.
3. What did you expect to happen when applying this setup?
4. What happened instead and how didn't it match your expectation?
## Trying out the Development Version
If you want to just install and try out the latest development version of
MkDocs you can do so with the following command. This can be useful if you
MkDocs (in case it already contains a fix for your issue),
you can do so with the following command. This can be useful if you
want to provide feedback for a new feature or want to confirm if a bug you
have encountered is fixed in the git master. It is **strongly** recommended
that you do this within a [virtualenv].
```bash
pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz
pip install git+https://github.com/mkdocs/mkdocs.git
```
## Installing for Development
## Installing MkDocs for Development
First you'll need to fork and clone the repository. Once you have a local
copy, run the following command. It is **strongly** recommended that you do
this within a [virtualenv].
Note that for development you can just use [Hatch] directly as described below. If you wish to install a local clone of MkDocs anyway, you can run `pip install --editable .`. It is **strongly** recommended that you do this within a [virtualenv].
## Installing Hatch
The main tool that is used for development is [Hatch]. It manages dependencies (in a virtualenv that is created on the fly) and is also the command runner.
So first, [install it][install Hatch]. Ideally in an isolated way with **`pipx install hatch`** (after [installing `pipx`]), or just `pip install hatch` as a more well-known way.
## Running all checks
To run **all** checks that are required for MkDocs, just run the following command in the cloned MkDocs repository:
```bash
pip install --editable .
hatch run all
```
This will install MkDocs in development mode which binds the `mkdocs` command
to the git repository.
**This will encompass all of the checks mentioned below.**
## Running the tests
All checks need to pass.
To run the tests, it is recommended that you use [Hatch].
### Running tests
Install Hatch using [pip] by running the command `pip install hatch`.
Then the test suite can be run for MkDocs by running the command `hatch run all` in the
root of your MkDocs repository.
To run the test suite for MkDocs, run the following commands:
```bash
hatch run test:test
hatch run integration:test
```
It will attempt to run the tests against all of the Python versions we
support. So don't be concerned if you are missing some. The rest
will be verified by [GitHub Actions] when you submit a pull request.
## Formatting the code
### Python code style
Python code within MkDocs' code base is formatted using [Black] and [Isort].
You can automatically format the code according to these tools
with `hatch run style:format`.
Python code within MkDocs' code base is formatted using [Black] and [Isort] and lint-checked using [Ruff], all of which are configured in `pyproject.toml`.
You can automatically check and format the code according to these tools with the following command:
```bash
hatch run style:fix
```
The code is also type-checked using [mypy] - also configured in `pyproject.toml`, it can be run like this:
```bash
hatch run types:check
```
### Other style checks
There are several other checks, such as spelling and CSS style. To run all of them, use this command:
```bash
hatch run lint:check
```
### Documentation of MkDocs itself
After making edits to files under the `docs/` dir, you can preview the site locally using the following command:
```bash
hatch run docs:serve
```
Note that any 'WARNING' should be resolved before submitting a contribution.
Documentation files are also checked by markdownlint, so you should run this as well:
```bash
hatch run lint:check
```
If you add a new plugin to mkdocs.yml, you don't need to add it to any "requirements" file, because that is managed automatically.
> INFO: If you don't want to use Hatch, for documentation you can install requirements into a virtualenv, in one of these ways (with `.venv` being the virtualenv directory):
>
> ```bash
> .venv/bin/pip install -r requirements/requirements-docs.txt # Exact versions of dependencies.
> .venv/bin/pip install -r $(mkdocs get-deps) # Latest versions of all dependencies.
> ```
## Translating themes
To localize a theme to your favorite language, follow the guide on [Translating
Themes]. We welcome translation Pull Requests!
To localize a theme to your favorite language, follow the guide on [Translating Themes]. We welcome translation pull requests!
## Submitting Pull Requests
@@ -83,6 +141,11 @@ Once you think the code is ready to be reviewed, push
it to your fork and send a pull request. For a change to be accepted it will
most likely need to have tests and documentation if it is a new feature.
When working with a pull request branch:
Unless otherwise agreed, prefer `commit` over `amend`, and `merge` over `rebase`. Avoid force-pushes, otherwise review history is much harder to navigate. For the end result, the "unclean" history is fine because most pull requests are squash-merged on GitHub.
Do *not* add to *release-notes.md*, this will be written later.
### Submitting changes to the builtin themes
When installed with `i18n` support (`pip install 'mkdocs[i18n]'`), MkDocs allows
@@ -110,12 +173,20 @@ Contributors are not expected to provide translations with their changes to
a theme's templates. However, they are expected to include an updated `pot`
file so that everything is ready for translators to do their job.
## Code of Conduct
Everyone interacting in the MkDocs project's codebases, issue trackers, chat
rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
[virtualenv]: https://virtualenv.pypa.io/en/latest/user_guide.html
[pip]: https://pip.pypa.io/en/stable/
[Hatch]: https://hatch.pypa.io/
[install Hatch]: https://hatch.pypa.io/latest/install/#pip
[installing `pipx`]: https://pypa.github.io/pipx/installation/
[GitHub Actions]: https://docs.github.com/actions
[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
[Translating Themes]: https://www.mkdocs.org/dev-guide/translations/
[Jinja's i18n extension]: https://jinja.palletsprojects.com/en/latest/extensions/#i18n-extension
[Black]: https://pypi.org/project/black/
[Isort]: https://pypi.org/project/isort/
[Ruff]: https://docs.astral.sh/ruff/
[Black]: https://black.readthedocs.io/
[Isort]: https://pycqa.github.io/isort/
[mypy]: https://mypy-lang.org/

2
mkdocs/themes/mkdocs/css/base.css
View File

@@ -226,7 +226,7 @@ blockquote {
text-align: left;
}
.admonition.note, details.note { /* csslint allow: adjoining-classes */
.admonition.note, details.note, .admonition.info, details.info { /* csslint allow: adjoining-classes */
color: #2e6b89;
background-color: #e2f0f7;
border-color: #bce8f1;