diff --git a/.markdownlintrc b/.markdownlintrc index c0e8a9b3..b3763aed 100644 --- a/.markdownlintrc +++ b/.markdownlintrc @@ -22,6 +22,9 @@ // Allow inline HTML "MD033": false, + // First line heading + "MD041": false, + // Disable named references validation "MD052": false } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 527abf61..6bac5771 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,192 @@ # Contributing to MkDocs -See the contributing guide in the documentation for an -introduction to contributing to MkDocs. +An introduction to contributing to the MkDocs project. - +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: + +- Code patches via pull requests +- Documentation improvements +- Bug reports and patch reviews + +For information about available communication channels please refer to the +[README](https://github.com/mkdocs/mkdocs#readme) file in our +GitHub repository. + +## 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. If you get an error, please include the full error message and +traceback. + +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 (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 git+https://github.com/mkdocs/mkdocs.git +``` + +## Installing MkDocs for Development + +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 +hatch run all +``` + +**This will encompass all of the checks mentioned below.** + +All checks need to pass. + +### Running tests + +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. + +### Python code style + +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! + +## Submitting Pull Requests + +If you're considering a large code contribution to MkDocs, please prefer to +open an issue first to get early feedback on the idea. + +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 +themes to support being translated into various languages (referred to as +locales) if they respect [Jinja's i18n extension] by wrapping text placeholders +with `{% trans %}` and `{% endtrans %}` tags. + +Each time a translatable text placeholder is added, removed or changed in a +theme template, the theme's Portable Object Template (`pot`) file needs to be +updated by running the `extract_messages` command. To update the +`pot` file for both built-in themes, run these commands: + +```bash +pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs +pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs +``` + +The updated `pot` file should be included in a PR with the updated template. +The updated `pot` file will allow translation contributors to propose the +translations needed for their preferred language. See the guide on [Translating +Themes] for details. + +NOTE: +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 +[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 +[Ruff]: https://docs.astral.sh/ruff/ +[Black]: https://black.readthedocs.io/ +[Isort]: https://pycqa.github.io/isort/ +[mypy]: https://mypy-lang.org/ diff --git a/docs/about/contributing.md b/docs/about/contributing.md index 6d03be0a..ea38c9bf 100644 --- a/docs/about/contributing.md +++ b/docs/about/contributing.md @@ -1,121 +1 @@ -# Contributing to MkDocs - -An introduction to contributing to the MkDocs project. - -The MkDocs project welcomes, and depends, on contributions from developers and -users in the open source community. Contributions can be made in a number of -ways, a few examples are: - -- Code patches via pull requests -- Documentation improvements -- 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 -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 -traceback. - -## Testing 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 -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 -``` - -## Installing 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]. - -```bash -pip install --editable . -``` - -This will install MkDocs in development mode which binds the `mkdocs` command -to the git repository. - -## Running the tests - -To run the tests, it is recommended that you use [Hatch]. - -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. - -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 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`. - -## Translating themes - -To localize a theme to your favorite language, follow the guide on [Translating -Themes]. We welcome translation Pull Requests! - -## Submitting Pull Requests - -If you're considering a large code contribution to MkDocs, please prefer to -open an issue first to get early feedback on the idea. - -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. - -### Submitting changes to the builtin themes - -When installed with `i18n` support (`pip install 'mkdocs[i18n]'`), MkDocs allows -themes to support being translated into various languages (referred to as -locales) if they respect [Jinja's i18n extension] by wrapping text placeholders -with `{% trans %}` and `{% endtrans %}` tags. - -Each time a translatable text placeholder is added, removed or changed in a -theme template, the theme's Portable Object Template (`pot`) file needs to be -updated by running the `extract_messages` command. To update the -`pot` file for both built-in themes, run these commands: - -```bash -pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs -pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs -``` - -The updated `pot` file should be included in a PR with the updated template. -The updated `pot` file will allow translation contributors to propose the -translations needed for their preferred language. See the guide on [Translating -Themes] for details. - -NOTE: -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. - -[virtualenv]: https://virtualenv.pypa.io/en/latest/user_guide.html -[pip]: https://pip.pypa.io/en/stable/ -[Hatch]: https://hatch.pypa.io/ -[GitHub Actions]: https://docs.github.com/actions -[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ -[Translating Themes]: ../dev-guide/translations.md -[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/ +--8<-- "CONTRIBUTING.md" diff --git a/docs/hooks.py b/docs/hooks.py index ad88111a..15e52dbb 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -1,8 +1,12 @@ +from __future__ import annotations + import re from pathlib import Path +from typing import TYPE_CHECKING -from mkdocs.config.defaults import MkDocsConfig -from mkdocs.structure.nav import Page +if TYPE_CHECKING: + from mkdocs.config.defaults import MkDocsConfig + from mkdocs.structure.nav import Page def _get_language_of_translation_file(path: Path) -> str: @@ -13,7 +17,7 @@ def _get_language_of_translation_file(path: Path) -> str: return m[1] -def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs): +def on_page_markdown(markdown: str, page: Page, config: MkDocsConfig, **kwargs) -> str | None: if page.file.src_uri == 'user-guide/choosing-your-theme.md': here = Path(config.config_file_path).parent diff --git a/mkdocs.yml b/mkdocs.yml index f8570754..56b65d87 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,9 @@ nav: extra_css: - css/extra.css +exclude_docs: | + *.py + markdown_extensions: - toc: permalink:  diff --git a/mkdocs/themes/mkdocs/css/base.css b/mkdocs/themes/mkdocs/css/base.css index 26103413..a396ae53 100644 --- a/mkdocs/themes/mkdocs/css/base.css +++ b/mkdocs/themes/mkdocs/css/base.css @@ -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;