From 91837c94e3142a69520607ed31832113e4224508 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sat, 9 Dec 2023 13:35:59 +0100 Subject: [PATCH 1/4] Drop the file CONTRIBUTING.md, in preparation for a move --- CONTRIBUTING.md | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 527abf61..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,6 +0,0 @@ -# Contributing to MkDocs - -See the contributing guide in the documentation for an -introduction to contributing to MkDocs. - - From f40f3bfe92c20a4b8c0e9c804fc5e4d6c4208698 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sat, 9 Dec 2023 13:37:53 +0100 Subject: [PATCH 2/4] Move CONTRIBUTING.md doc to the root --- docs/about/contributing.md => CONTRIBUTING.md | 2 +- docs/hooks.py | 18 +++++++++++++++--- mkdocs.yml | 3 +++ 3 files changed, 19 insertions(+), 4 deletions(-) rename docs/about/contributing.md => CONTRIBUTING.md (98%) diff --git a/docs/about/contributing.md b/CONTRIBUTING.md similarity index 98% rename from docs/about/contributing.md rename to CONTRIBUTING.md index 6d03be0a..840c3ba8 100644 --- a/docs/about/contributing.md +++ b/CONTRIBUTING.md @@ -115,7 +115,7 @@ file so that everything is ready for translators to do their job. [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 +[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/ diff --git a/docs/hooks.py b/docs/hooks.py index ad88111a..ddf0db05 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -1,8 +1,20 @@ +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 +from mkdocs.structure.files import File, Files + +if TYPE_CHECKING: + from mkdocs.config.defaults import MkDocsConfig + from mkdocs.structure.nav import Page + + +def on_files(files: Files, config: MkDocsConfig) -> None: + f = File('about/contributing.md', config.docs_dir, config.site_dir, config.use_directory_urls) + f.abs_src_path = str(Path(config.config_file_path).parent.joinpath('CONTRIBUTING.md')) + files.append(f) def _get_language_of_translation_file(path: Path) -> str: @@ -13,7 +25,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:  From 9af473c71c5b8734d040ddb854716a736fd82433 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sat, 9 Dec 2023 15:16:38 +0100 Subject: [PATCH 3/4] Let's use pymdownx.snippets for the move --- .markdownlintrc | 3 +++ docs/about/contributing.md | 1 + docs/hooks.py | 8 -------- 3 files changed, 4 insertions(+), 8 deletions(-) create mode 100644 docs/about/contributing.md 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/docs/about/contributing.md b/docs/about/contributing.md new file mode 100644 index 00000000..ea38c9bf --- /dev/null +++ b/docs/about/contributing.md @@ -0,0 +1 @@ +--8<-- "CONTRIBUTING.md" diff --git a/docs/hooks.py b/docs/hooks.py index ddf0db05..15e52dbb 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -4,19 +4,11 @@ import re from pathlib import Path from typing import TYPE_CHECKING -from mkdocs.structure.files import File, Files - if TYPE_CHECKING: from mkdocs.config.defaults import MkDocsConfig from mkdocs.structure.nav import Page -def on_files(files: Files, config: MkDocsConfig) -> None: - f = File('about/contributing.md', config.docs_dir, config.site_dir, config.use_directory_urls) - f.abs_src_path = str(Path(config.config_file_path).parent.joinpath('CONTRIBUTING.md')) - files.append(f) - - def _get_language_of_translation_file(path: Path) -> str: with path.open(encoding='utf-8') as f: translation_line = f.readline() From 09ff0ab247fa8d00d84ac7800dd17c82b11473b6 Mon Sep 17 00:00:00 2001 From: Oleh Prypin Date: Sun, 10 Dec 2023 14:00:09 +0100 Subject: [PATCH 4/4] Update CONTRIBUTING.md --- CONTRIBUTING.md | 137 +++++++++++++++++++++++------- mkdocs/themes/mkdocs/css/base.css | 2 +- 2 files changed, 105 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 840c3ba8..6bac5771 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/ 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;