diff --git a/.gitattributes b/.gitattributes index d9d23f9b..8362faa0 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,10 +1,10 @@ -mkdocs/contrib/search/lunr-language/** linguist-vendored -mkdocs/themes/mkdocs/js/** linguist-vendored -mkdocs/themes/mkdocs/js/base.js linguist-vendored=false -mkdocs/themes/mkdocs/css/** linguist-vendored -mkdocs/themes/mkdocs/css/base.css linguist-vendored=false -mkdocs/themes/readthedocs/js/** linguist-vendored -mkdocs/themes/readthedocs/js/theme.js linguist-vendored=false -mkdocs/themes/readthedocs/css/** linguist-vendored -mkdocs/themes/readthedocs/css/theme_extra.css linguist-vendored=false +properdocs/contrib/search/lunr-language/** linguist-vendored +properdocs/themes/mkdocs/js/** linguist-vendored +properdocs/themes/mkdocs/js/base.js linguist-vendored=false +properdocs/themes/mkdocs/css/** linguist-vendored +properdocs/themes/mkdocs/css/base.css linguist-vendored=false +properdocs/themes/readthedocs/js/** linguist-vendored +properdocs/themes/readthedocs/js/theme.js linguist-vendored=false +properdocs/themes/readthedocs/css/** linguist-vendored +properdocs/themes/readthedocs/css/theme_extra.css linguist-vendored=false docs/img/plugin-events.svg linguist-generated diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bf93e0d2..51cada0c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -98,7 +98,7 @@ jobs: - name: Check packaged files shell: bash -e -x {0} run: | - expected_wheel=(-emkdocs/{templates/sitemap.xml,config/base.py,py.typed,contrib/search/lunr-language/lunr.nl.js,themes/{mkdocs,readthedocs}/{base.html,locales/{de,es}/LC_MESSAGES/messages.mo}}) + expected_wheel=(-eproperdocs/{templates/sitemap.xml,config/base.py,py.typed,contrib/search/lunr-language/lunr.nl.js,themes/{mkdocs,readthedocs}/{base.html,locales/{de,es}/LC_MESSAGES/messages.mo}}) expected_sdist=("${expected_wheel[@]}" -e{pyproject.toml,hatch_build.py}) - test "$(tar -ztf dist/mkdocs-*.tar.gz | grep -F "${expected_sdist[@]}" | tee /dev/stderr | wc -l)" -eq "${#expected_sdist[@]}" - test "$(unzip -l dist/mkdocs-*any.whl | grep -F "${expected_wheel[@]}" | tee /dev/stderr | wc -l)" -eq "${#expected_wheel[@]}" + test "$(tar -ztf dist/properdocs-*.tar.gz | grep -F "${expected_sdist[@]}" | tee /dev/stderr | wc -l)" -eq "${#expected_sdist[@]}" + test "$(unzip -l dist/properdocs-*any.whl | grep -F "${expected_wheel[@]}" | tee /dev/stderr | wc -l)" -eq "${#expected_wheel[@]}" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 16d74e52..5c5d028e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -17,4 +17,4 @@ jobs: - name: Install dependencies run: pip install --no-deps -r requirements/requirements-docs.txt - name: Build site - run: mkdocs build --strict + run: properdocs build --strict diff --git a/.gitignore b/.gitignore index cebf2abb..d68c3bfd 100644 --- a/.gitignore +++ b/.gitignore @@ -66,5 +66,5 @@ target/ venv/ ENV/ -# MkDocs documentation +# ProperDocs documentation site*/ diff --git a/.jshintignore b/.jshintignore index 8b54bdfa..911cbd36 100644 --- a/.jshintignore +++ b/.jshintignore @@ -1,9 +1,9 @@ -mkdocs/themes/**/js/jquery-**.min.js -mkdocs/themes/mkdocs/js/highlight.pack.js -mkdocs/themes/mkdocs/js/bootstrap.bundle.min.js -mkdocs/themes/mkdocs/js/modernizr-**.min.js -mkdocs/themes/readthedocs/js/theme.js -mkdocs/themes/readthedocs/js/html5shiv.min.js -mkdocs/contrib/search/templates/search/lunr.js -mkdocs/contrib/search/lunr-language/lunr.**.js -mkdocs/contrib/search/lunr-language/tinyseg.js +properdocs/themes/**/js/jquery-**.min.js +properdocs/themes/mkdocs/js/highlight.pack.js +properdocs/themes/mkdocs/js/bootstrap.bundle.min.js +properdocs/themes/mkdocs/js/modernizr-**.min.js +properdocs/themes/readthedocs/js/theme.js +properdocs/themes/readthedocs/js/html5shiv.min.js +properdocs/contrib/search/templates/search/lunr.js +properdocs/contrib/search/lunr-language/lunr.**.js +properdocs/contrib/search/lunr-language/tinyseg.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 510ef6f6..d6d0e6e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,8 @@ -# Contributing to MkDocs +# Contributing to ProperDocs -An introduction to contributing to the MkDocs project. +An introduction to contributing to the ProperDocs project. -The MkDocs project welcomes contributions from developers and +The ProperDocs 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,12 +11,12 @@ 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#readme) file in our +[README](https://github.com/properdocs/properdocs#readme) file in our GitHub repository. ## Reporting an Issue -Please include as much detail as you can. Let us know your platform and MkDocs +Please include as much detail as you can. Let us know your platform and ProperDocs 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. @@ -34,19 +34,19 @@ It is particularly helpful if an issue report touches on all of these aspects: ## 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), +ProperDocs (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 +pip install git+https://github.com/properdocs/properdocs.git ``` ## Installing 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]. +Note that for development you can just use [Hatch] directly as described below. If you wish to install a local clone of ProperDocs anyway, you can run `pip install --editable .`. It is **strongly** recommended that you do this within a [virtualenv]. ## Installing Hatch @@ -56,7 +56,7 @@ So first, [install it][install Hatch]. Ideally in an isolated way with **`pipx i ## Running all checks -To run **all** checks that are required for MkDocs, just run the following command in the cloned MkDocs repository: +To run **all** checks that are required for ProperDocs, just run the following command in the cloned ProperDocs repository: ```bash hatch run all @@ -68,7 +68,7 @@ All checks need to pass. ### Running tests -To run the test suite for MkDocs, run the following commands: +To run the test suite for ProperDocs, run the following commands: ```bash hatch run test:test @@ -81,7 +81,7 @@ 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`. +Python code within ProperDocs' 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: @@ -103,7 +103,7 @@ There are several other checks, such as spelling and JS style. To run all of the hatch run lint:check ``` -### Documentation of MkDocs itself +### Documentation of ProperDocs itself After making edits to files under the `docs/` dir, you can preview the site locally using the following command: @@ -125,7 +125,7 @@ If you add a new plugin to mkdocs.yml, you don't need to add it to any "requirem > > ```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. +> .venv/bin/pip install -r $(properdocs get-deps) # Latest versions of all dependencies. > ``` ## Translating themes @@ -134,7 +134,7 @@ To localize a theme to your favorite language, follow the guide on [Translating ## Submitting Pull Requests -If you're considering a large code contribution to MkDocs, please prefer to +If you're considering a large code contribution to ProperDocs, 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 @@ -148,7 +148,7 @@ 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 +When installed with `i18n` support (`pip install 'properdocs[i18n]'`), ProperDocs 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. @@ -159,8 +159,8 @@ 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 +pybabel extract --project=ProperDocs --copyright-holder=ProperDocs --msgid-bugs-address='https://github.com/properdocs/properdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file properdocs/themes/babel.cfg --output-file properdocs/themes/mkdocs/messages.pot properdocs/themes/mkdocs +pybabel extract --project=ProperDocs --copyright-holder=ProperDocs --msgid-bugs-address='https://github.com/properdocs/properdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file properdocs/themes/babel.cfg --output-file properdocs/themes/readthedocs/messages.pot properdocs/themes/readthedocs ``` The updated `pot` file should be included in a PR with the updated template. @@ -175,7 +175,7 @@ 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 +Everyone interacting in the ProperDocs 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 @@ -184,7 +184,7 @@ rooms, and mailing lists is expected to follow the [PyPA Code of Conduct]. [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/ +[Translating Themes]: https://properdocs.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/ diff --git a/FUNDING.yml b/FUNDING.yml index 2e9b9627..733f4c6c 100644 --- a/FUNDING.yml +++ b/FUNDING.yml @@ -1 +1 @@ -github: mkdocs +github: properdocs diff --git a/README.md b/README.md index 7b665a23..a63d6605 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# MkDocs +# ProperDocs > *Project documentation with Markdown* @@ -6,26 +6,26 @@ [![Build Status][GHAction-image]][GHAction-link] [![Coverage Status][codecov-image]][codecov-link] -MkDocs is a **fast**, **simple** and **downright gorgeous** static site +ProperDocs is a **fast**, **simple** and **downright gorgeous** static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. It is designed to be easy to use and can be extended with third-party themes, plugins, and Markdown extensions. -Please see the [Documentation][mkdocs] for an introductory tutorial and a full +Please see the [Documentation][properdocs] for an introductory tutorial and a full user guide. ## Features - Build static HTML files from Markdown files. -- Use Plugins and Markdown Extensions to enhance MkDocs. +- Use Plugins and Markdown Extensions to enhance ProperDocs. - Use the built-in themes, third party themes or create your own. - Publish your documentation anywhere that static files can be served. - Much more! ## Support -If you need help with MkDocs, do not hesitate to get in contact with us! +If you need help with ProperDocs, do not hesitate to get in contact with us! - For questions and high-level discussions, use **[Discussions]** on GitHub. - For small questions, a good alternative is the **[Chat room]** on @@ -33,7 +33,7 @@ If you need help with MkDocs, do not hesitate to get in contact with us! - To report a bug or make a feature request, open an **[Issue]** on GitHub. Please note that we may only provide -support for problems/questions regarding core features of MkDocs. Any +support for problems/questions regarding core features of ProperDocs. Any questions or bug reports about features of third-party themes, plugins, extensions or similar should be made to their respective projects. But, such questions are *not* banned from the [chat room]. @@ -42,38 +42,38 @@ Make sure to stick around to answer some questions as well! ## Links -- [Official Documentation][mkdocs] +- [Official Documentation][properdocs] - [Latest Release Notes][release-notes] - [Catalog of third-party plugins, themes and recipes][catalog] -## Contributing to MkDocs +## Contributing to ProperDocs -The MkDocs project welcomes, and depends on, contributions from developers and +The ProperDocs project welcomes, and depends on, contributions from developers and users in the open source community. Please see the [Contributing Guide] for information on how you can help. ## Code of Conduct -Everyone interacting in the MkDocs project's codebases, issue trackers, and +Everyone interacting in the ProperDocs project's codebases, issue trackers, and discussion forums is expected to follow the [PyPA Code of Conduct]. -[codecov-image]: https://codecov.io/github/mkdocs/mkdocs/coverage.svg?branch=master -[codecov-link]: https://codecov.io/github/mkdocs/mkdocs?branch=master -[pypi-v-image]: https://img.shields.io/pypi/v/mkdocs.svg -[pypi-v-link]: https://pypi.org/project/mkdocs/ -[GHAction-image]: https://github.com/mkdocs/mkdocs/actions/workflows/ci.yml/badge.svg -[GHAction-link]: https://github.com/mkdocs/mkdocs/actions/workflows/ci.yml +[codecov-image]: https://codecov.io/github/properdocs/properdocs/coverage.svg?branch=master +[codecov-link]: https://codecov.io/github/properdocs/properdocs?branch=master +[pypi-v-image]: https://img.shields.io/pypi/v/properdocs.svg +[pypi-v-link]: https://pypi.org/project/properdocs/ +[GHAction-image]: https://github.com/properdocs/properdocs/actions/workflows/ci.yml/badge.svg +[GHAction-link]: https://github.com/properdocs/properdocs/actions/workflows/ci.yml -[mkdocs]: https://www.mkdocs.org -[Issue]: https://github.com/mkdocs/mkdocs/issues -[Discussions]: https://github.com/mkdocs/mkdocs/discussions +[properdocs]: https://properdocs.org +[Issue]: https://github.com/properdocs/properdocs/issues +[Discussions]: https://github.com/properdocs/properdocs/discussions [Chat room]: https://gitter.im/mkdocs/community -[release-notes]: https://www.mkdocs.org/about/release-notes/ -[Contributing Guide]: https://www.mkdocs.org/about/contributing/ +[release-notes]: https://properdocs.org/about/release-notes/ +[Contributing Guide]: https://properdocs.org/about/contributing/ [PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ -[catalog]: https://github.com/mkdocs/catalog +[catalog]: https://github.com/properdocs/catalog ## License -[BSD-2-Clause](https://github.com/mkdocs/mkdocs/blob/master/LICENSE) +[BSD-2-Clause](https://github.com/properdocs/properdocs/blob/master/LICENSE) diff --git a/docs/CNAME b/docs/CNAME index d7525f16..ffb9ce08 100644 --- a/docs/CNAME +++ b/docs/CNAME @@ -1 +1 @@ -www.mkdocs.org +properdocs.org diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 4fd81c15..3cc2406f 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -4,22 +4,22 @@ ## Upgrading -To upgrade MkDocs to the latest version, use pip: +To upgrade ProperDocs to the latest version, use pip: ```bash -pip install -U mkdocs +pip install -U properdocs ``` -You can determine your currently installed version using `mkdocs --version`: +You can determine your currently installed version using `properdocs --version`: ```console -$ mkdocs --version -mkdocs, version 1.5.0 from /path/to/mkdocs (Python 3.10) +$ properdocs --version +properdocs, version 1.5.0 from /path/to/properdocs (Python 3.10) ``` ## Maintenance team -The current and past members of the MkDocs team. +The current and past members of the ProperDocs team. * [@tomchristie](https://github.com/tomchristie/) * [@d0ugal](https://github.com/d0ugal/) @@ -75,7 +75,7 @@ Other changes: MkDocs 1.5 had a change in behavior in deducing the page titles from the first heading. Unfortunately this could cause unescaped HTML tags or entities to appear in edge cases. -Now tags are always fully sanitized from the title. Though it still remains the case that [`Page.title`][mkdocs.structure.pages.Page.title] is expected to contain HTML entities and is passed directly to the themes. +Now tags are always fully sanitized from the title. Though it still remains the case that [`Page.title`][properdocs.structure.pages.Page.title] is expected to contain HTML entities and is passed directly to the themes. Images (notably, emojis in some extensions) get preserved in the title only through their `alt` attribute's value. @@ -194,15 +194,15 @@ Other changes: #### Plugins can add multiple handlers for the same event type, at multiple priorities -See [`mkdocs.plugins.CombinedEvent`][] in [**documentation**](../dev-guide/plugins.md#event-priorities). Context: #3448 +See [`properdocs.plugins.CombinedEvent`][] in [**documentation**](../dev-guide/plugins.md#event-priorities). Context: #3448 -#### Enabling true generated files and expanding the [`File`][mkdocs.structure.files.File] API +#### Enabling true generated files and expanding the [`File`][properdocs.structure.files.File] API -See [**documentation**][mkdocs.structure.files.File]. +See [**documentation**][properdocs.structure.files.File]. -* There is a new pair of attributes [`File.content_string`][mkdocs.structure.files.File.content_string]/[`content_bytes`][mkdocs.structure.files.File.content_bytes] that becomes the official API for obtaining the content of a file and is used by MkDocs itself. +* There is a new pair of attributes [`File.content_string`][properdocs.structure.files.File.content_string]/[`content_bytes`][properdocs.structure.files.File.content_bytes] that becomes the official API for obtaining the content of a file and is used by MkDocs itself. - This replaces the old approach where one had to manually read the file located at [`File.abs_src_path`][mkdocs.structure.files.File.abs_src_path], although that is still the primary action that these new attributes do under the hood. + This replaces the old approach where one had to manually read the file located at [`File.abs_src_path`][properdocs.structure.files.File.abs_src_path], although that is still the primary action that these new attributes do under the hood. * The content of a `File` can be backed by a string and no longer has to be a real existing file at `abs_src_path`. @@ -210,29 +210,29 @@ See [**documentation**][mkdocs.structure.files.File]. Further, `abs_src_path` is no longer guaranteed to be present and can be `None` instead. MkDocs itself still uses physical files in all cases, but eventually plugins will appear that don't populate this attribute. -* There is a new constructor [`File.generated()`][mkdocs.structure.files.File.generated] that should be used by plugins instead of the `File()` constructor. It is much more convenient because one doesn't need to manually look up the values such as `docs_dir` and `use_directory_urls`. Its signature is one of: +* There is a new constructor [`File.generated()`][properdocs.structure.files.File.generated] that should be used by plugins instead of the `File()` constructor. It is much more convenient because one doesn't need to manually look up the values such as `docs_dir` and `use_directory_urls`. Its signature is one of: ```python - f = File.generated(config: MkDocsConfig, src_uri: str, content: str | bytes) - f = File.generated(config: MkDocsConfig, src_uri: str, abs_src_path: str) + f = File.generated(config: ProperDocsConfig, src_uri: str, content: str | bytes) + f = File.generated(config: ProperDocsConfig, src_uri: str, abs_src_path: str) ``` This way, it is now extremely easy to add a virtual file even from a hook: ```python - def on_files(files: Files, config: MkDocsConfig): + def on_files(files: Files, config: ProperDocsConfig): files.append(File.generated(config, 'fake/path.md', content="Hello, world!")) ``` For large content it is still best to use physical files, but one no longer needs to manipulate the path by providing a fake unused `docs_dir`. -* There is a new attribute [`File.generated_by`][mkdocs.structure.files.File.generated_by] that arose by convention - for generated files it should be set to the name of the plugin (the key in the `plugins:` collection) that produced this file. This attribute is populated automatically when using the `File.generated()` constructor. +* There is a new attribute [`File.generated_by`][properdocs.structure.files.File.generated_by] that arose by convention - for generated files it should be set to the name of the plugin (the key in the `plugins:` collection) that produced this file. This attribute is populated automatically when using the `File.generated()` constructor. -* It is possible to set the [`edit_uri`][mkdocs.structure.files.File.edit_uri] attribute of a `File`, for example from a plugin or hook, to make it different from the default (equal to `src_uri`), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the `edit_uri` to that source file or script accordingly. +* It is possible to set the [`edit_uri`][properdocs.structure.files.File.edit_uri] attribute of a `File`, for example from a plugin or hook, to make it different from the default (equal to `src_uri`), and this will be reflected in the edit link of the document. This can be useful because some pages aren't backed by a real file and are instead created dynamically from some other source file or script. So a hook could set the `edit_uri` to that source file or script accordingly. * The `File` object now stores its original `src_dir`, `dest_dir`, `use_directory_urls` values as attributes. -* Fields of `File` are computed on demand but cached. Only the three above attributes are primary ones, and partly also [`dest_uri`][mkdocs.structure.files.File.dest_uri]. This way, it is possible to, for example, overwrite `dest_uri` of a `File`, and `abs_dest_path` will be calculated based on it. However you need to clear the attribute first using `del f.abs_dest_path`, because the values are cached. +* Fields of `File` are computed on demand but cached. Only the three above attributes are primary ones, and partly also [`dest_uri`][properdocs.structure.files.File.dest_uri]. This way, it is possible to, for example, overwrite `dest_uri` of a `File`, and `abs_dest_path` will be calculated based on it. However you need to clear the attribute first using `del f.abs_dest_path`, because the values are cached. * `File` instances are now hashable (can be used as keys of a `dict`). Two files can no longer be considered "equal" unless it's the exact same instance of `File`. @@ -278,7 +278,7 @@ Context: #3429 * The `sitemap.xml.gz` file is slightly more reproducible and no longer changes on every build, but instead only once per day (upon a date change). Context: #3460 -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.3...1.6.0). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.5.3...1.6.0). ## Version 1.5.3 (2023-09-18) @@ -292,9 +292,9 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp * Plugins can now set `File.page` to their own subclass of `Page`. There is also now a warning if `File.page` is set to anything other than a strict subclass of `Page`. (#3367, #3381) - Note that just instantiating a `Page` [sets the file automatically](https://github.com/mkdocs/mkdocs/blob/f94ab3f62d0416d484d81a0c695c8ca86ab3b975/mkdocs/structure/pages.py#L34), so care needs to be taken not to create an unneeded `Page`. + Note that just instantiating a `Page` [sets the file automatically](https://github.com/properdocs/properdocs/blob/f94ab3f62d0416d484d81a0c695c8ca86ab3b975/mkdocs/structure/pages.py#L34), so care needs to be taken not to create an unneeded `Page`. -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.2...1.5.3). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.5.2...1.5.3). ## Version 1.5.2 (2023-08-02) @@ -306,7 +306,7 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp Plugins should be free to append strings to `config.extra_javascript`, but when reading the values, they must still make sure to read it as `str(value)` in case it is an `ExtraScriptValue` item. For querying the attributes such as `.type` you need to check `isinstance` first. Static type checking will guide you in that. (#3324) -See [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.1...1.5.2). +See [commit log](https://github.com/properdocs/properdocs/compare/1.5.1...1.5.2). ## Version 1.5.1 (2023-07-28) @@ -314,7 +314,7 @@ See [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.1...1.5.2). * Bugfix (regression in 1.5.0): Prevent errors for special setups that have 3 conflicting files, such as `index.html`, `index.md` *and* `README.md` (#3314) -See [commit log](https://github.com/mkdocs/mkdocs/compare/1.5.0...1.5.1). +See [commit log](https://github.com/properdocs/properdocs/compare/1.5.0...1.5.1). ## Version 1.5.0 (2023-07-26) @@ -332,7 +332,7 @@ The way it works is by scanning `mkdocs.yml` for `themes:`, `plugins:`, `markdow Of course, you're welcome to use a "virtualenv" with such a command. Also note that for environments that require stability (for example CI) directly installing deps in this way is not a very reliable approach as it precludes dependency pinning. -The command allows overriding which config file is used (instead of `mkdocs.yml` in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See [`mkdocs get-deps --help`](../user-guide/cli.md#mkdocs-get-deps). +The command allows overriding which config file is used (instead of `mkdocs.yml` in the current directory) as well as which catalog of projects is used (instead of downloading it from the default location). See [`mkdocs get-deps --help`](../user-guide/cli.md#properdocs-get-deps). Context: #3205 @@ -485,21 +485,21 @@ See [**documentation**](../dev-guide/themes.md#picking-up-css-and-javascript-fro * `File` has a new attribute `inclusion`. Its value is calculated from both the `exclude_docs` and `not_in_nav` configs, and implements their behavior. Plugins can read this value or write to it. New `File` instances by default follow whatever the configs say, but plugins can choose to make this decision explicitly, per file. -* When creating a `File`, one can now set a `dest_uri` directly, rather than having to update it (and other dependent attributes) after creation. [Context](https://github.com/mkdocs/mkdocs/commit/d5af6426c52421f1113f6dcc591de1e01bea48bd) +* When creating a `File`, one can now set a `dest_uri` directly, rather than having to update it (and other dependent attributes) after creation. [Context](https://github.com/properdocs/properdocs/commit/d5af6426c52421f1113f6dcc591de1e01bea48bd) * A new config option was added - `DictOfItems`. Similarly to `ListOfItems`, it validates a mapping of config options that all have the same type. Keys are arbitrary but always strings. Context: #3242 * A new function `get_plugin_logger` was added. In order to opt into a standardized way for plugins to log messages, please use the idiom: ```python - log = mkdocs.plugins.get_plugin_logger(__name__) + log = properdocs.plugins.get_plugin_logger(__name__) ... log.info("Hello, world") ``` Context: #3245 -* `SubConfig` config option can be conveniently subclassed with a particular type of config specified. For example, `class ExtraScript(SubConfig[ExtraScriptValue]):`. To see how this is useful, search for this class in code. [Context](https://github.com/mkdocs/mkdocs/commit/73e503990e3e3504bfe1cb627d41a7e97970687e) +* `SubConfig` config option can be conveniently subclassed with a particular type of config specified. For example, `class ExtraScript(SubConfig[ExtraScriptValue]):`. To see how this is useful, search for this class in code. [Context](https://github.com/properdocs/properdocs/commit/73e503990e3e3504bfe1cb627d41a7e97970687e) * Bugfix: `SubConfig` had a bug where paths (from `FilesystemObject` options) were not made relative to the main config file as intended, because `config_file_path` was not properly inherited to it. This is now fixed. Context: #3265 @@ -512,15 +512,15 @@ See [**documentation**](../dev-guide/themes.md#picking-up-css-and-javascript-fro async_ = Type(bool, default=False) ``` - Previously making a config key with a reserved name was impossible with new-style schemas. [Context](https://github.com/mkdocs/mkdocs/commit/1db8e884fa7135a49adf7740add5d875a16a18bc) + Previously making a config key with a reserved name was impossible with new-style schemas. [Context](https://github.com/properdocs/properdocs/commit/1db8e884fa7135a49adf7740add5d875a16a18bc) * `Theme` has its attributes properly declared and gained new attributes `theme.locale`, `theme.custom_dir`. * Some type annotations were made more precise. For example: - * The `context` parameter has gained the type `TemplateContext` (`TypedDict`). [Context](https://github.com/mkdocs/mkdocs/commit/0f793b9984c7e6a1d53ce874e7d17b6d27ebf4b2) - * The classes `Page`, `Section`, `Link` now have a common base class `StructureItem`. [Context](https://github.com/mkdocs/mkdocs/commit/01be507e30b05db0a4c44ef05ba62b2098010653) - * Some methods stopped accepting `Config` and only accept `MkDocsConfig` as was originally intended. [Context](https://github.com/mkdocs/mkdocs/commit/c459cd24fc0320333f51525e9cf681d4a8370f50) + * The `context` parameter has gained the type `TemplateContext` (`TypedDict`). [Context](https://github.com/properdocs/properdocs/commit/0f793b9984c7e6a1d53ce874e7d17b6d27ebf4b2) + * The classes `Page`, `Section`, `Link` now have a common base class `StructureItem`. [Context](https://github.com/properdocs/properdocs/commit/01be507e30b05db0a4c44ef05ba62b2098010653) + * Some methods stopped accepting `Config` and only accept `ProperDocsConfig` as was originally intended. [Context](https://github.com/properdocs/properdocs/commit/c459cd24fc0320333f51525e9cf681d4a8370f50) * `config.mdx_configs` got a proper type. Context: #3229 ### Theme updates @@ -547,7 +547,7 @@ This can be used for config overrides on the fly. See updated section at the bot The command to use this is `mkdocs build -f -`. In previous versions doing this led to an error. -[Context](https://github.com/mkdocs/mkdocs/commit/d5bb15fa108da86a8e53fb7d84109d8f8d9d6453) +[Context](https://github.com/properdocs/properdocs/commit/d5bb15fa108da86a8e53fb7d84109d8f8d9d6453) ### New command line flags @@ -569,13 +569,13 @@ The command to use this is `mkdocs build -f -`. In previous versions doing this * Accessing the `user_configs` attribute of a `Config` is deprecated. Note: instead of `config.user_configs[*]['theme']['custom_dir']`, please use the new attribute `config.theme.custom_dir`. -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.3...1.5.0). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.4.3...1.5.0). ## Version 1.4.3 (2023-05-02) * Bugfix: for the `hooks` feature, modules no longer fail to load if using some advanced Python features like dataclasses (#3193) -* Bugfix: Don't create `None` sitemap entries if the page has no populated URL - affects sites that exclude some files from navigation ([`07a297b`](https://github.com/mkdocs/mkdocs/commit/07a297b3b4de4a1b49469b1497ee34039b9f38fa)) +* Bugfix: Don't create `None` sitemap entries if the page has no populated URL - affects sites that exclude some files from navigation ([`07a297b`](https://github.com/properdocs/properdocs/commit/07a297b3b4de4a1b49469b1497ee34039b9f38fa)) * "readthedocs" theme: * Accessibility: add aria labels to Home logo (#3129) and search inputs (#3046) @@ -586,7 +586,7 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp * Fixed `zh_CN` translation (#3125) * `tr_TR` translation becomes just `tr` - usage should remain unaffected (#3195) -See [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.2...1.4.3). +See [commit log](https://github.com/properdocs/properdocs/compare/1.4.2...1.4.3). ## Version 1.4.2 (2022-11-01) @@ -612,7 +612,7 @@ See [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.2...1.4.3). * Plugin-related warnings look more readable (#3016) -See [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.1...1.4.2). +See [commit log](https://github.com/properdocs/properdocs/compare/1.4.1...1.4.2). ## Version 1.4.1 (2022-10-15) @@ -635,7 +635,7 @@ See [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.1...1.4.2). * The ['mkdocs' package](https://pypi.org/project/mkdocs/#files) (wheel and source) is now produced by Hatch build system and pyproject.toml instead of setup.py (#2988) -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.4.0...1.4.1). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.4.0...1.4.1). ## Version 1.4.0 (2022-09-27) @@ -687,7 +687,7 @@ To not make a breaking change, there's no change to how *this* property is used, These consistently use forward slashes, and are now the definitive source that MkDocs itself uses. -See [source code](https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/structure/files.py#L151). +See [source code](https://github.com/properdocs/properdocs/blob/1.4.0/mkdocs/structure/files.py#L151). As a related tip: you should also stop using `os.path.*` or `pathlib.Path()` to deal with these paths, and instead use `posixpath.*` or `pathlib.PurePosixPath()` @@ -697,11 +697,11 @@ As a related tip: you should also stop using `os.path.*` or `pathlib.Path()` to MkDocs' plugin event methods now have type annotations. You might have been adding annotations to events already, but now they will be validated to match the original. -See [source code](https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/plugins.py#L165) and [documentation](../dev-guide/plugins.md#events). +See [source code](https://github.com/properdocs/properdocs/blob/1.4.0/mkdocs/plugins.py#L165) and [documentation](../dev-guide/plugins.md#events). -One big update is that now you should annotate method parameters more specifically as `config: defaults.MkDocsConfig` instead of `config: base.Config`. This not only makes it clear that it is the [main config of MkDocs itself](https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/config/defaults.py), but also provides type-safe access through attributes of the object (see next section). +One big update is that now you should annotate method parameters more specifically as `config: defaults.ProperDocsConfig` instead of `config: base.Config`. This not only makes it clear that it is the [main config of MkDocs itself](https://github.com/properdocs/properdocs/blob/1.4.0/mkdocs/config/defaults.py), but also provides type-safe access through attributes of the object (see next section). -See [source code](https://github.com/mkdocs/mkdocs/blob/1.4.0/mkdocs/config/defaults.py) and [documentation](../dev-guide/plugins.md#on_event_name). +See [source code](https://github.com/properdocs/properdocs/blob/1.4.0/mkdocs/config/defaults.py) and [documentation](../dev-guide/plugins.md#on_event_name). #### Rework ConfigOption schemas as class-based (#2962) @@ -740,7 +740,7 @@ class MyPluginConfig(base.Config): bar = c.Type(str, default='') class MyPlugin(plugins.BasePlugin[MyPluginConfig]): - def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs): + def on_page_markdown(self, markdown: str, *, config: defaults.ProperDocsConfig, **kwargs): if self.config.foo < 5: # Error, `foo` might be `None`, need to check first. if config.site_url.startswith('http:'): # Error, MkDocs' `site_url` also might be `None`. return markdown + self.config.baz # Error, no such attribute `baz`! @@ -750,7 +750,7 @@ This lets you notice the errors from a static type checker before running the co ```python class MyPlugin(plugins.BasePlugin[MyPluginConfig]): - def on_page_markdown(self, markdown: str, *, config: defaults.MkDocsConfig, **kwargs): + def on_page_markdown(self, markdown: str, *, config: defaults.ProperDocsConfig, **kwargs): if self.config.foo is not None and self.config.foo < 5: # OK, `int < int` is valid. if (config.site_url or '').startswith('http:'): # OK, `str.startswith(str)` is valid. return markdown + self.config.bar # OK, `str + str` is valid. @@ -846,7 +846,7 @@ Deprecated config option classes: `ConfigItems` (#2983), `OptionallyRequired` (# * Bugfix (regression in 1.2): Support listening on an IPv6 address in `mkdocs serve`. (#2951) -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.3.1...1.4.0). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.3.1...1.4.0). ## Version 1.3.1 (2022-07-19) @@ -861,7 +861,7 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp * Built-in themes now also support these languages: * Italian (#2860) -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.3.0...1.3.1). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.3.0...1.3.1). ## Version 1.3.0 (2022-03-26) @@ -875,7 +875,7 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp * New option `anonymize_ip` for Google Analytics. * Dependencies were upgraded: jQuery upgraded to 3.6.0, Modernizr.js dropped, and others. - See [documentation of config options for the theme](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs) + See [documentation of config options for the theme](https://properdocs.org/user-guide/choosing-your-theme/#readthedocs) * Built-in themes now also support these languages: * German (#2633) @@ -887,7 +887,7 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp Normally MkDocs never reaches into any other directories (so this feature shouldn't be necessary), but some plugins and extensions may do so. - See [documentation](https://www.mkdocs.org/user-guide/configuration/#watch). + See [documentation](https://properdocs.org/user-guide/configuration/#watch). * New `--no-history` option for `gh_deploy` (#2594) @@ -911,9 +911,9 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp * Recursively validate `nav` (#2680) - Validation of the nested `nav` structure has been reworked to report errors early and reliably. Some [edge cases](https://github.com/mkdocs/mkdocs/blob/b7272150bbc9bf8f66c878f6517742de3528972b/mkdocs/tests/config/config_options_tests.py#L783) have been declared invalid. + Validation of the nested `nav` structure has been reworked to report errors early and reliably. Some [edge cases](https://github.com/properdocs/properdocs/blob/b7272150bbc9bf8f66c878f6517742de3528972b/mkdocs/tests/config/config_options_tests.py#L783) have been declared invalid. -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.2.3...1.3.0). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.2.3...1.3.0). ## Version 1.2.4 (2022-03-26) @@ -942,7 +942,7 @@ Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/comp * Bugfix: Python version 3.10 was displayed incorrectly in `--version` (#2618) -Other small improvements; see [commit log](https://github.com/mkdocs/mkdocs/compare/1.2.2...1.2.3). +Other small improvements; see [commit log](https://github.com/properdocs/properdocs/compare/1.2.2...1.2.3). ## Version 1.2.2 (2021-07-18) diff --git a/docs/dev-guide/README.md b/docs/dev-guide/README.md index 183365e0..8d262bc5 100644 --- a/docs/dev-guide/README.md +++ b/docs/dev-guide/README.md @@ -1,12 +1,12 @@ # Developer Guide -Extending MkDocs +Extending ProperDocs --- -The MkDocs Developer Guide provides documentation for developers of third +The ProperDocs Developer Guide provides documentation for developers of third party themes and plugins. Please see the [Contributing Guide] for information -on contributing to MkDocs itself. You can jump directly to a page listed +on contributing to ProperDocs itself. You can jump directly to a page listed below, or use the *next* and *previous* buttons in the navigation bar at the top of the page to move through the documentation in order. diff --git a/docs/dev-guide/api.md b/docs/dev-guide/api.md index b0917402..b4e6bf55 100644 --- a/docs/dev-guide/api.md +++ b/docs/dev-guide/api.md @@ -2,23 +2,23 @@ NOTE: The main entry point to the API is through [Events](plugins.md#events) that are received by plugins. These events' descriptions link back to this page. -::: mkdocs.structure.files.Files +::: properdocs.structure.files.Files options: show_root_heading: true -::: mkdocs.structure.files.File +::: properdocs.structure.files.File options: show_root_heading: true -::: mkdocs.config.base.Config +::: properdocs.config.base.Config options: show_root_heading: true -::: mkdocs.utils.templates.TemplateContext +::: properdocs.utils.templates.TemplateContext options: show_root_heading: true show_if_no_docstring: true -::: mkdocs.livereload.LiveReloadServer +::: properdocs.livereload.LiveReloadServer options: show_root_heading: true diff --git a/docs/dev-guide/plugins.md b/docs/dev-guide/plugins.md index e0305c3c..646cfeb1 100644 --- a/docs/dev-guide/plugins.md +++ b/docs/dev-guide/plugins.md @@ -1,21 +1,21 @@ -# MkDocs Plugins +# ProperDocs Plugins -A Guide to installing, using and creating MkDocs Plugins +A Guide to installing, using and creating ProperDocs Plugins --- ## Installing Plugins Before a plugin can be used, it must be installed on the system. If you are -using a plugin which comes with MkDocs, then it was installed when you installed -MkDocs. However, to install third party plugins, you need to determine the +using a plugin which comes with ProperDocs, then it was installed when you installed +ProperDocs. However, to install third party plugins, you need to determine the appropriate package name and install it using `pip`: ```bash -pip install mkdocs-foo-plugin +pip install properdocs-foo-plugin ``` -WARNING: Installing an MkDocs plugin means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing. +WARNING: Installing a ProperDocs plugin means installing a Python package and executing any code that the author has put in there. So, exercise the usual caution; there's no attempt at sandboxing. Once a plugin has been successfully installed, it is ready to use. It just needs to be [enabled](#using-plugins) in the configuration file. The [Catalog] @@ -56,15 +56,15 @@ For a list of default plugins and how to override them, see the ## Developing Plugins -Like MkDocs, plugins must be written in Python. It is generally expected that +Like ProperDocs, plugins must be written in Python. It is generally expected that each plugin would be distributed as a separate Python module, although it is -possible to define multiple plugins in the same module. At a minimum, a MkDocs +possible to define multiple plugins in the same module. At a minimum, a ProperDocs Plugin must consist of a [BasePlugin] subclass and an [entry point] which points to it. ### BasePlugin -A subclass of `mkdocs.plugins.BasePlugin` should define the behavior of the plugin. +A subclass of `properdocs.plugins.BasePlugin` should define the behavior of the plugin. The class generally consists of actions to perform on specific events in the build process as well as a configuration scheme for the plugin. @@ -75,16 +75,16 @@ All `BasePlugin` subclasses contain the following attributes: A tuple of configuration validation instances. Each item must consist of a two item tuple in which the first item is the string name of the configuration option and the second item is an instance of -`mkdocs.config.config_options.BaseConfigOption` or any of its subclasses. +`properdocs.config.config_options.BaseConfigOption` or any of its subclasses. For example, the following `config_scheme` defines three configuration options: `foo`, which accepts a string; `bar`, which accepts an integer; and `baz`, which accepts a boolean value. ```python -class MyPlugin(mkdocs.plugins.BasePlugin): +class MyPlugin(properdocs.plugins.BasePlugin): config_scheme = ( - ('foo', mkdocs.config.config_options.Type(str, default='a default value')), - ('bar', mkdocs.config.config_options.Type(int, default=0)), - ('baz', mkdocs.config.config_options.Type(bool, default=True)) + ('foo', properdocs.config.config_options.Type(str, default='a default value')), + ('bar', properdocs.config.config_options.Type(int, default=0)), + ('baz', properdocs.config.config_options.Type(bool, default=True)) ) ``` @@ -95,12 +95,12 @@ class MyPlugin(mkdocs.plugins.BasePlugin): > To get type safety benefits, if you're targeting only MkDocs 1.4+, define the config schema as a class instead: > > ```python -> class MyPluginConfig(mkdocs.config.base.Config): -> foo = mkdocs.config.config_options.Type(str, default='a default value') -> bar = mkdocs.config.config_options.Type(int, default=0) -> baz = mkdocs.config.config_options.Type(bool, default=True) +> class MyPluginConfig(properdocs.config.base.Config): +> foo = properdocs.config.config_options.Type(str, default='a default value') +> bar = properdocs.config.config_options.Type(int, default=0) +> baz = properdocs.config.config_options.Type(bool, default=True) > -> class MyPlugin(mkdocs.plugins.BasePlugin[MyPluginConfig]): +> class MyPlugin(properdocs.plugins.BasePlugin[MyPluginConfig]): > ... > ``` @@ -109,7 +109,7 @@ class MyPlugin(mkdocs.plugins.BasePlugin): >! EXAMPLE: > > ```python -> from mkdocs.config import base, config_options as c +> from properdocs.config import base, config_options as c > > class _ValidationOptions(base.Config): > enabled = c.Type(bool, default=True) @@ -143,7 +143,7 @@ class MyPlugin(mkdocs.plugins.BasePlugin): > > ```python > import numbers -> from mkdocs.config import base, config_options as c +> from properdocs.config import base, config_options as c > > class _Rectangle(base.Config): > width = c.Type(numbers.Real) # required @@ -169,11 +169,11 @@ class MyPlugin(mkdocs.plugins.BasePlugin): When the user's configuration is loaded, the above scheme will be used to validate the configuration and fill in any defaults for settings not provided by the user. The validation classes may be any of the classes -provided in `mkdocs.config.config_options` or a third party subclass defined +provided in `properdocs.config.config_options` or a third party subclass defined in the plugin. Any settings provided by the user which fail validation or are not defined -in the `config_scheme` will raise a `mkdocs.config.base.ValidationError`. +in the `config_scheme` will raise a `properdocs.config.base.ValidationError`. #### config @@ -204,7 +204,7 @@ All `BasePlugin` subclasses contain the following method(s): #### load_config(options) Loads configuration from a dictionary of options. Returns a tuple of -`(errors, warnings)`. This method is called by MkDocs during configuration +`(errors, warnings)`. This method is called by ProperDocs during configuration validation and should not need to be called by the plugin. #### on_<event_name>() @@ -221,7 +221,7 @@ returns `None`), then the original, unmodified object is used. The keyword arguments are simply provided to give context and/or supply data which may be used to determine how the positional argument should be modified. It is good practice to accept keyword arguments as `**kwargs`. In the event that -additional keywords are provided to an event in a future version of MkDocs, +additional keywords are provided to an event in a future version of ProperDocs, there will be no need to alter your plugin. For example, the following event would add an additional static_template to @@ -239,7 +239,7 @@ class MyPlugin(BasePlugin): > To get type safety benefits, if you're targeting only MkDocs 1.4+, access config options as attributes instead: > > ```python -> def on_config(self, config: MkDocsConfig): +> def on_config(self, config: ProperDocsConfig): > config.theme.static_templates.add('my_template.html') > return config > ``` @@ -269,25 +269,25 @@ There are three kinds of events: [Global Events], [Page Events] and #### One-time Events -One-time events run once per `mkdocs` invocation. The only case where these tangibly differ from [global events](#global-events) is for `mkdocs serve`: global events, unlike these, will run multiple times -- once per *build*. +One-time events run once per `properdocs` invocation. The only case where these tangibly differ from [global events](#global-events) is for `properdocs serve`: global events, unlike these, will run multiple times -- once per *build*. ##### on_startup -::: mkdocs.plugins.BasePlugin.on_startup +::: properdocs.plugins.BasePlugin.on_startup options: show_root_heading: false show_root_toc_entry: false ##### on_shutdown -::: mkdocs.plugins.BasePlugin.on_shutdown +::: properdocs.plugins.BasePlugin.on_shutdown options: show_root_heading: false show_root_toc_entry: false ##### on_serve -::: mkdocs.plugins.BasePlugin.on_serve +::: properdocs.plugins.BasePlugin.on_serve options: show_root_heading: false show_root_toc_entry: false @@ -300,49 +300,49 @@ entire site. ##### on_config -::: mkdocs.plugins.BasePlugin.on_config +::: properdocs.plugins.BasePlugin.on_config options: show_root_heading: false show_root_toc_entry: false ##### on_pre_build -::: mkdocs.plugins.BasePlugin.on_pre_build +::: properdocs.plugins.BasePlugin.on_pre_build options: show_root_heading: false show_root_toc_entry: false ##### on_files -::: mkdocs.plugins.BasePlugin.on_files +::: properdocs.plugins.BasePlugin.on_files options: show_root_heading: false show_root_toc_entry: false ##### on_nav -::: mkdocs.plugins.BasePlugin.on_nav +::: properdocs.plugins.BasePlugin.on_nav options: show_root_heading: false show_root_toc_entry: false ##### on_env -::: mkdocs.plugins.BasePlugin.on_env +::: properdocs.plugins.BasePlugin.on_env options: show_root_heading: false show_root_toc_entry: false ##### on_post_build -::: mkdocs.plugins.BasePlugin.on_post_build +::: properdocs.plugins.BasePlugin.on_post_build options: show_root_heading: false show_root_toc_entry: false ##### on_build_error -::: mkdocs.plugins.BasePlugin.on_build_error +::: properdocs.plugins.BasePlugin.on_build_error options: show_root_heading: false show_root_toc_entry: false @@ -356,21 +356,21 @@ called after the [env] event and before any [page events]. ##### on_pre_template -::: mkdocs.plugins.BasePlugin.on_pre_template +::: properdocs.plugins.BasePlugin.on_pre_template options: show_root_heading: false show_root_toc_entry: false ##### on_template_context -::: mkdocs.plugins.BasePlugin.on_template_context +::: properdocs.plugins.BasePlugin.on_template_context options: show_root_heading: false show_root_toc_entry: false ##### on_post_template -::: mkdocs.plugins.BasePlugin.on_post_template +::: properdocs.plugins.BasePlugin.on_post_template options: show_root_heading: false show_root_toc_entry: false @@ -383,42 +383,42 @@ page events are called after the [post_template] event and before the ##### on_pre_page -::: mkdocs.plugins.BasePlugin.on_pre_page +::: properdocs.plugins.BasePlugin.on_pre_page options: show_root_heading: false show_root_toc_entry: false ##### on_page_read_source -::: mkdocs.plugins.BasePlugin.on_page_read_source +::: properdocs.plugins.BasePlugin.on_page_read_source options: show_root_heading: false show_root_toc_entry: false ##### on_page_markdown -::: mkdocs.plugins.BasePlugin.on_page_markdown +::: properdocs.plugins.BasePlugin.on_page_markdown options: show_root_heading: false show_root_toc_entry: false ##### on_page_content -::: mkdocs.plugins.BasePlugin.on_page_content +::: properdocs.plugins.BasePlugin.on_page_content options: show_root_heading: false show_root_toc_entry: false ##### on_page_context -::: mkdocs.plugins.BasePlugin.on_page_context +::: properdocs.plugins.BasePlugin.on_page_context options: show_root_heading: false show_root_toc_entry: false ##### on_post_page -::: mkdocs.plugins.BasePlugin.on_post_page +::: properdocs.plugins.BasePlugin.on_post_page options: show_root_heading: false show_root_toc_entry: false @@ -429,7 +429,7 @@ For each event type, corresponding methods of plugins are called in the order th Since MkDocs 1.4, plugins can choose to set a priority value for their events. Events with higher priority are called first. Events without a chosen priority get a default of 0. Events that have the same priority are ordered as they appear in the config. -#### ::: mkdocs.plugins.event_priority +#### ::: properdocs.plugins.event_priority > NEW: **New in version 1.6** > @@ -437,24 +437,24 @@ Since MkDocs 1.4, plugins can choose to set a priority value for their events. E > > `CombinedEvent` makes this possible. > -> #### ::: mkdocs.plugins.CombinedEvent +> #### ::: properdocs.plugins.CombinedEvent ### Handling Errors -MkDocs defines four error types: +ProperDocs defines four error types: -#### ::: mkdocs.exceptions.MkDocsException +#### ::: properdocs.exceptions.ProperDocsException -#### ::: mkdocs.exceptions.ConfigurationError +#### ::: properdocs.exceptions.ConfigurationError -#### ::: mkdocs.exceptions.BuildError +#### ::: properdocs.exceptions.BuildError -#### ::: mkdocs.exceptions.PluginError +#### ::: properdocs.exceptions.PluginError Unexpected and uncaught exceptions will interrupt the build process and produce typical Python tracebacks, which are useful for debugging your code. However, users generally find tracebacks overwhelming and often miss the helpful error -message. Therefore, MkDocs will catch any of the errors listed above, retrieve +message. Therefore, ProperDocs will catch any of the errors listed above, retrieve the error message, and exit immediately with only the helpful message displayed to the user. @@ -467,8 +467,8 @@ The [on_build_error] event will be triggered for any exception. For example: ```python -from mkdocs.exceptions import PluginError -from mkdocs.plugins import BasePlugin +from properdocs.exceptions import PluginError +from properdocs.plugins import BasePlugin class MyPlugin(BasePlugin): @@ -486,14 +486,14 @@ class MyPlugin(BasePlugin): ### Logging in plugins -To ensure that your plugins' log messages adhere with MkDocs' formatting and `--verbose`/`--debug` flags, please write the logs to a logger under the `mkdocs.plugins.` namespace. +To ensure that your plugins' log messages adhere with ProperDocs' formatting and `--verbose`/`--debug` flags, please write the logs to a logger under the `properdocs.plugins.` namespace. > EXAMPLE: > > ```python > import logging > -> log = logging.getLogger(f"mkdocs.plugins.{__name__}") +> log = logging.getLogger(f"properdocs.plugins.{__name__}") > > log.warning("File '%s' not found. Breaks the build if --strict is passed", my_file_name) > log.info("Shown normally") @@ -503,24 +503,24 @@ To ensure that your plugins' log messages adhere with MkDocs' formatting and `-- > log.debug("Very expensive calculation only for debugging: %s", get_my_diagnostics()) > ``` -`log.error()` is another logging level that is differentiated by its look, but in all other ways it functions the same as `warning`, so it's strange to use it. If your plugin encounters an actual error, it is best to just interrupt the build by raising [`mkdocs.exceptions.PluginError`][] (which will also log an ERROR message). +`log.error()` is another logging level that is differentiated by its look, but in all other ways it functions the same as `warning`, so it's strange to use it. If your plugin encounters an actual error, it is best to just interrupt the build by raising [`properdocs.exceptions.PluginError`][] (which will also log an ERROR message). > NEW: **New in version 1.5** > -> MkDocs now provides a `get_plugin_logger()` convenience function that returns a logger like the above that is also prefixed with the plugin's name. +> ProperDocs now provides a `get_plugin_logger()` convenience function that returns a logger like the above that is also prefixed with the plugin's name. > -> #### ::: mkdocs.plugins.get_plugin_logger +> #### ::: properdocs.plugins.get_plugin_logger ### Entry Point Plugins need to be packaged as Python libraries (distributed on PyPI separate -from MkDocs) and each must register as a Plugin via a setuptools `entry_points`. +from ProperDocs) and each must register as a Plugin via a setuptools `entry_points`. Add the following to your `setup.py` script: ```python entry_points={ - 'mkdocs.plugins': [ + 'properdocs.plugins': [ 'pluginname = path.to.some_plugin:SomePluginClass', ] } @@ -535,7 +535,7 @@ entry point. ```python entry_points={ - 'mkdocs.plugins': [ + 'properdocs.plugins': [ 'featureA = path.to.my_plugins:PluginA', 'featureB = path.to.my_plugins:PluginB' ] @@ -543,7 +543,7 @@ entry_points={ ``` Note that registering a plugin does not activate it. The user still needs to -tell MkDocs to use it via the config. +tell ProperDocs to use it via the config. ### Publishing a Plugin @@ -561,6 +561,6 @@ You should publish a package on [PyPI], then add it to the [Catalog] for discove [post_template]: #on_post_template [static_templates]: ../user-guide/configuration.md#static_templates [Template Events]: #template-events -[catalog]: https://github.com/mkdocs/catalog +[catalog]: https://github.com/properdocs/catalog [on_build_error]: #on_build_error [PyPI]: https://pypi.org/ diff --git a/docs/dev-guide/themes.md b/docs/dev-guide/themes.md index ea4b9911..6acd36d7 100644 --- a/docs/dev-guide/themes.md +++ b/docs/dev-guide/themes.md @@ -6,7 +6,7 @@ A guide to creating and distributing custom themes. NOTE: If you are looking for existing third party themes, they are listed in the -[community wiki] page and the [MkDocs project catalog][catalog]. If you want to +[community wiki] page and the [ProperDocs project catalog][catalog]. If you want to share a theme you create, you should list it there. When creating a new theme, you can either follow the steps in this guide to @@ -15,8 +15,8 @@ basic, yet complete, theme with all the boilerplate required. **You can find this base theme on [GitHub][basic theme]**. It contains detailed comments in the code to describe the different features and their usage. -[community wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes -[catalog]: https://github.com/mkdocs/catalog#-theming +[community wiki]: https://github.com/properdocs/properdocs/wiki/ProperDocs-Themes +[catalog]: https://github.com/properdocs/catalog#-theming [basic theme]: https://github.com/mkdocs/mkdocs-basic-theme ## Creating a custom theme @@ -109,9 +109,9 @@ respectively. If you wish to write your own theme, it is recommended to start with one of the [built-in themes] and modify it accordingly. NOTE: -As MkDocs uses [Jinja] as its template engine, you have access to all the +As ProperDocs uses [Jinja] as its template engine, you have access to all the power of Jinja, including [template inheritance]. You may notice that the -themes included with MkDocs make extensive use of template inheritance and +themes included with ProperDocs make extensive use of template inheritance and blocks, allowing users to easily override small bits and pieces of the templates from the theme [custom_dir]. Therefore, the built-in themes are implemented in a `base.html` file, which `main.html` extends. Although not @@ -125,7 +125,7 @@ themes for consistency. ### Picking up CSS and JavaScript from the config -MkDocs defines the top-level [extra_css](../user-guide/configuration.md#extra_css) and [extra_javascript](../user-guide/configuration.md#extra_javascript) configs. These are lists of files. +ProperDocs defines the top-level [extra_css](../user-guide/configuration.md#extra_css) and [extra_javascript](../user-guide/configuration.md#extra_javascript) configs. These are lists of files. The theme must include the HTML that links the items from these configs, otherwise the configs will be non-functional. You can see the recommended way to render both of them in the [base example above](#basic-theme). @@ -133,7 +133,7 @@ The theme must include the HTML that links the items from these configs, otherwi > > The items of the `config.extra_javascript` list used to be simple strings but now became objects that have these fields: `path`, `type`, `async`, `defer`. > -> In that version, MkDocs also gained the [`script_tag` filter](#script_tag). +> In that version, ProperDocs also gained the [`script_tag` filter](#script_tag). > > >? EXAMPLE: **Obsolete style:** > > @@ -200,7 +200,7 @@ the `mkdocs_theme.yml` configuration file and any Python files. ### Dot Files -Theme authors can explicitly force MkDocs to ignore files by starting a file or +Theme authors can explicitly force ProperDocs to ignore files by starting a file or directory name with a dot. Any of the following files would be ignored: ```text @@ -231,7 +231,7 @@ The following variables are available globally on any template. #### config -The `config` variable is an instance of MkDocs' config object generated from the +The `config` variable is an instance of ProperDocs' config object generated from the `mkdocs.yml` config file. While you can use any config option, some commonly used options include: @@ -254,7 +254,7 @@ defined by the [nav] configuration setting. [nav]: ../user-guide/configuration.md#nav -::: mkdocs.structure.nav.Navigation +::: properdocs.structure.nav.Navigation options: show_root_heading: false show_root_toc_entry: true @@ -264,12 +264,12 @@ defined by the [nav] configuration setting. In addition to the iterable of [navigation objects](#navigation-objects), the `nav` object contains the following attributes: -::: mkdocs.structure.nav.Navigation.homepage +::: properdocs.structure.nav.Navigation.homepage options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Navigation.pages +::: properdocs.structure.nav.Navigation.pages options: show_root_full_path: false heading_level: 5 @@ -310,14 +310,14 @@ navigation as a nested list. #### base_url -The `base_url` provides a relative path to the root of the MkDocs project. While +The `base_url` provides a relative path to the root of the ProperDocs project. While this can be used directly by prepending it to a local relative URL, it is best to use the [url](#url) template filter, which is smarter about how it applies `base_url`. #### mkdocs_version -Contains the current MkDocs version. +Contains the current ProperDocs version. #### build_date_utc @@ -340,7 +340,7 @@ the `page` variable contains a `page` object. The same `page` objects are used as `page` [navigation objects](#navigation-objects) in the global [navigation](#nav) and in the [pages](#pages) template variable. -::: mkdocs.structure.pages.Page +::: properdocs.structure.pages.Page options: show_root_heading: false show_root_toc_entry: true @@ -349,17 +349,17 @@ as `page` [navigation objects](#navigation-objects) in the global All `page` objects contain the following attributes: -::: mkdocs.structure.pages.Page.title +::: properdocs.structure.pages.Page.title options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.content +::: properdocs.structure.pages.Page.content options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.toc +::: properdocs.structure.pages.Page.toc options: show_root_full_path: false heading_level: 5 @@ -378,7 +378,7 @@ for a page. ``` -::: mkdocs.structure.pages.Page.meta +::: properdocs.structure.pages.Page.meta options: show_root_full_path: false heading_level: 5 @@ -406,7 +406,7 @@ documentation page. {% endfor %} ``` -::: mkdocs.structure.pages.Page.url +::: properdocs.structure.pages.Page.url options: show_root_full_path: false heading_level: 5 @@ -418,12 +418,12 @@ page. {{ page.title }} ``` -::: mkdocs.structure.pages.Page.file +::: properdocs.structure.pages.Page.file options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.abs_url +::: properdocs.structure.pages.Page.abs_url options: show_root_full_path: false heading_level: 5 @@ -433,17 +433,17 @@ For example, if `site_url: https://example.com/`, then the value of `site_url: https://example.com/bar/`, then the value of `page.abs_url` for the page `foo.md` would be `/bar/foo/`. -::: mkdocs.structure.pages.Page.canonical_url +::: properdocs.structure.pages.Page.canonical_url options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.edit_url +::: properdocs.structure.pages.Page.edit_url options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.is_homepage +::: properdocs.structure.pages.Page.is_homepage options: show_root_full_path: false heading_level: 5 @@ -456,49 +456,49 @@ on the homepage: {% if not page.is_homepage %}{{ page.title }} - {% endif %}{{ site_name }} ``` -::: mkdocs.structure.pages.Page.previous_page +::: properdocs.structure.pages.Page.previous_page options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.next_page +::: properdocs.structure.pages.Page.next_page options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.StructureItem.parent +::: properdocs.structure.StructureItem.parent options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.children +::: properdocs.structure.pages.Page.children options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.active +::: properdocs.structure.pages.Page.active options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.is_section +::: properdocs.structure.pages.Page.is_section options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.is_page +::: properdocs.structure.pages.Page.is_page options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.pages.Page.is_link +::: properdocs.structure.pages.Page.is_link options: show_root_full_path: false heading_level: 5 #### AnchorLink -::: mkdocs.structure.toc.AnchorLink +::: properdocs.structure.toc.AnchorLink options: show_root_heading: false show_root_toc_entry: true @@ -519,11 +519,11 @@ of those attributes as defined below: A `section` navigation object defines a named section in the navigation and contains a list of child navigation objects. Note that sections do not contain -URLs and are not links of any kind. However, by default, MkDocs sorts index +URLs and are not links of any kind. However, by default, ProperDocs sorts index pages to the top and the first child might be used as the URL for a section if a theme chooses to do so. -::: mkdocs.structure.nav.Section +::: properdocs.structure.nav.Section options: show_root_heading: false show_root_toc_entry: true @@ -532,37 +532,37 @@ theme chooses to do so. The following attributes are available on `section` objects: -::: mkdocs.structure.nav.Section.title +::: properdocs.structure.nav.Section.title options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.StructureItem.parent +::: properdocs.structure.StructureItem.parent options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Section.children +::: properdocs.structure.nav.Section.children options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Section.active +::: properdocs.structure.nav.Section.active options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Section.is_section +::: properdocs.structure.nav.Section.is_section options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Section.is_page +::: properdocs.structure.nav.Section.is_page options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Section.is_link +::: properdocs.structure.nav.Section.is_link options: show_root_full_path: false heading_level: 5 @@ -570,9 +570,9 @@ The following attributes are available on `section` objects: #### Link A `link` navigation object contains a link which does not point to an internal -MkDocs page. +ProperDocs page. -::: mkdocs.structure.nav.Link +::: properdocs.structure.nav.Link options: show_root_heading: false show_root_toc_entry: true @@ -581,42 +581,42 @@ MkDocs page. The following attributes are available on `link` objects: -::: mkdocs.structure.nav.Link.title +::: properdocs.structure.nav.Link.title options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Link.url +::: properdocs.structure.nav.Link.url options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.StructureItem.parent +::: properdocs.structure.StructureItem.parent options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Link.children +::: properdocs.structure.nav.Link.children options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Link.active +::: properdocs.structure.nav.Link.active options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Link.is_section +::: properdocs.structure.nav.Link.is_section options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Link.is_page +::: properdocs.structure.nav.Link.is_page options: show_root_full_path: false heading_level: 5 -::: mkdocs.structure.nav.Link.is_link +::: properdocs.structure.nav.Link.is_link options: show_root_full_path: false heading_level: 5 @@ -635,9 +635,9 @@ following `extra` configuration: extra: version: 0.13.0 links: - - https://github.com/mkdocs + - https://github.com/properdocs - https://docs.readthedocs.org/en/latest/builds.html#mkdocs - - https://www.mkdocs.org/ + - https://properdocs.org/ ``` And then displayed with this HTML in the custom theme. @@ -657,7 +657,7 @@ And then displayed with this HTML in the custom theme. ## Template Filters In addition to [Jinja's default filters], the following custom filters are -available to use in MkDocs templates: +available to use in ProperDocs templates: ### url @@ -676,7 +676,7 @@ Safely convert a Python object to a value in a JavaScript script. ```django ``` @@ -690,7 +690,7 @@ See how to use it in the [base example above](#basic-theme) ## Search and themes -As of MkDocs version *0.17* client side search support has been added to MkDocs +As of ProperDocs version *0.17* client side search support has been added to ProperDocs via the `search` plugin. A theme needs to provide a few things for the plugin to work with the theme. @@ -725,18 +725,18 @@ full search implementation to your theme.

Search Results

- +
-
+
Sorry, page not found.
``` The JavaScript in the plugin works by looking for the specific ID's used in the above HTML. The form input for the user to type the search query must be -identified with `id="mkdocs-search-query"` and the div where the results will be -placed must be identified with `id="mkdocs-search-results"`. +identified with `id="properdocs-search-query"` and the div where the results will be +placed must be identified with `id="properdocs-search-results"`. The plugin supports the following options being set in the [theme's configuration file], `mkdocs_theme.yml`: @@ -782,7 +782,7 @@ objects. If present, the `config` object contains the key/value pairs of config options defined for the plugin in the user's `mkdocs.yml` config file under -`plugings.search`. The `config` object was new in MkDocs version *1.0*. +`plugings.search`. The `config` object was new in ProperDocs version *1.0*. The `docs` object contains a list of document objects. Each document object is made up of a `location` (URL), a `title`, and `text` which can be used to create @@ -792,10 +792,10 @@ If present, the `index` object contains a pre-built index which offers performance improvements for larger sites. Note that the pre-built index is only created if the user explicitly enables the [prebuild_index] config option. Themes should expect the index to not be present, but can choose to use the -index when it is available. The `index` object was new in MkDocs version *1.0*. +index when it is available. The `index` object was new in ProperDocs version *1.0*. [Jinja2 template]: https://jinja.palletsprojects.com/ -[built-in themes]: https://github.com/mkdocs/mkdocs/tree/master/mkdocs/themes +[built-in themes]: https://github.com/properdocs/properdocs/tree/master/properdocs/themes [theme's configuration file]: #theme-configuration [lunr.js]: https://lunrjs.com/ [site_dir]: ../user-guide/configuration.md#site_dir @@ -804,11 +804,11 @@ index when it is available. The `index` object was new in MkDocs version *1.0*. ## Packaging Themes -MkDocs makes use of [Python packaging] to distribute themes. This comes with a +ProperDocs makes use of [Python packaging] to distribute themes. This comes with a few requirements. -To see an example of a package containing one theme, see the [MkDocs Bootstrap -theme] and to see a package that contains many themes, see the [MkDocs +To see an example of a package containing one theme, see the [ProperDocs Bootstrap +theme] and to see a package that contains many themes, see the [ProperDocs Bootswatch theme]. NOTE: @@ -821,8 +821,8 @@ your theme, your users can more easily install it, they can rely on a default [custom_dir] to make tweaks to your theme to better suit their needs. [Python packaging]: https://packaging.python.org/en/latest/ -[MkDocs Bootstrap theme]: https://mkdocs.github.io/mkdocs-bootstrap/ -[MkDocs Bootswatch theme]: https://mkdocs.github.io/mkdocs-bootswatch/ +[ProperDocs Bootstrap theme]: https://mkdocs.github.io/mkdocs-bootstrap/ +[ProperDocs Bootswatch theme]: https://mkdocs.github.io/mkdocs-bootswatch/ ### Package Layout @@ -860,7 +860,7 @@ from setuptools import setup, find_packages VERSION = '0.0.1' setup( - name="mkdocs-themename", + name="properdocs-themename", version=VERSION, url='', license='', @@ -870,7 +870,7 @@ setup( packages=find_packages(), include_package_data=True, entry_points={ - 'mkdocs.themes': [ + 'properdocs.themes': [ 'themename = theme_name', ] }, @@ -880,12 +880,12 @@ setup( Fill in the URL, license, description, author and author email address. -The name should follow the convention `mkdocs-themename` (like -`mkdocs-bootstrap` and `mkdocs-bootswatch`), starting with MkDocs, using +The name should follow the convention `properdocs-themename` (like +`mkdocs-bootstrap` and `mkdocs-bootswatch`), starting with ProperDocs, using hyphens to separate words and including the name of your theme. Most of the rest of the file can be left unedited. The last section we need to -change is the entry_points. This is how MkDocs finds the theme(s) you are +change is the entry_points. This is how ProperDocs finds the theme(s) you are including in the package. The name on the left is the one that users will use in their mkdocs.yml and the one on the right is the directory containing your theme files. @@ -931,7 +931,7 @@ theme: show_sidebar: false ``` -In addition to arbitrary options defined by the theme, MkDocs defines a few +In addition to arbitrary options defined by the theme, ProperDocs defines a few special options which alters its behavior: > BLOCK: @@ -999,7 +999,7 @@ With the above changes, your theme should now be ready to install. This can be done with pip, using `pip install .` if you are still in the same directory as the setup.py. -Most Python packages, including MkDocs, are distributed on PyPI. To do this, +Most Python packages, including ProperDocs, are distributed on PyPI. To do this, you should run the following command. ```bash @@ -1027,7 +1027,7 @@ will experience consistent behavior regardless of the theme they may choose. The method for managing translations is up to the developers of a theme. However, if a theme developer chooses to use the same mechanisms used by the built-in themes, the sections below outline how to enable and make use of the -same commands utilized by MkDocs. +same commands utilized by ProperDocs. [localization/translation]: ../user-guide/localizing-your-theme.md @@ -1037,12 +1037,12 @@ WARNING: As **[pybabel] is not installed by default** and most users will not have pybabel installed, theme developers and/or translators should make sure to have installed the necessary dependencies -(using `pip install 'mkdocs[i18n]'`) in order for the commands to be +(using `pip install 'properdocs[i18n]'`) in order for the commands to be available for use. The translation commands should be called from the root of your theme's working tree. -For an overview of the workflow used by MkDocs to translate the built-in +For an overview of the workflow used by ProperDocs to translate the built-in themes, see the appropriate [section] of the Contributing Guide and the [Translation Guide]. @@ -1054,7 +1054,7 @@ themes, see the appropriate [section] of the Contributing Guide and the > NOTE: If your theme inherits from an existing theme which already provides > translation catalogs, your theme's translations will be merged with the -> parent theme's translations during a MkDocs build. +> parent theme's translations during a ProperDocs build. > > This means that you only need to concentrate on the added translations. > Yet, you will still benefit from the translations of the parent theme. At @@ -1073,8 +1073,8 @@ Edit the templates by wrapping text in your HTML sources with --

This is an example theme for MkDocs.

-+

{% trans %}This is an example theme for MkDocs.{% endtrans %}

+-

This is an example theme for ProperDocs.

++

{% trans %}This is an example theme for ProperDocs.{% endtrans %}

It is designed to be read by looking at the theme HTML which is heavily @@ -1088,21 +1088,21 @@ running. While the Portable Object Template (`pot`) file created by the `extract_messages` command and the Portable Object (`po`) files created by the `init_catalog` and `update_catalog` commands are useful for creating and -editing translations, they are not used by MkDocs directly and do not need to -be included in a packaged release of a theme. When MkDocs builds a site with +editing translations, they are not used by ProperDocs directly and do not need to +be included in a packaged release of a theme. When ProperDocs builds a site with translations, it only makes use of the binary `mo` files(s) for the specified locale. Therefore, when [packaging a theme], make sure to include it in the "wheels", using a `MANIFEST.in` file or otherwise. Then, before building your Python package, you will want to ensure that the binary `mo` file for each locale is up-to-date by running the `compile_catalog` -command for each locale. MkDocs expects the binary `mo` files to be located at +command for each locale. ProperDocs expects the binary `mo` files to be located at `locales//LC_MESSAGES/messages.mo`, which the `compile_catalog` command automatically does for you. See [Testing theme translations] for details. NOTE: -As outlined in our [Translation Guide], the MkDocs project has chosen to +As outlined in our [Translation Guide], the ProperDocs project has chosen to include the `pot` and `po` files in our code repository, but not the `mo` files. This requires us to always run `compile_catalog` before packaging a new release regardless of whether any changes were made to a diff --git a/docs/dev-guide/translations.md b/docs/dev-guide/translations.md index 4c408b29..eb2fdddb 100644 --- a/docs/dev-guide/translations.md +++ b/docs/dev-guide/translations.md @@ -4,14 +4,14 @@ Theme localization guide. --- -The [built-in themes] that are included with MkDocs provide support for +The [built-in themes] that are included with ProperDocs provide support for translations. This is a guide for translators, which documents the process for contributing new translations and/or updating existing translations. For guidance on modifying the existing themes, see the [Contributing Guide][update themes]. To enable a specific translation see the documentation about the specific theme you are using in the [User Guide][built-in themes]. For translations of third-party themes, please see the documentation for those -themes. For a third-party theme to make use of MkDocs' translation tools and +themes. For a third-party theme to make use of ProperDocs' translation tools and methods, that theme must be properly [configured] to make use of those tools. NOTE: @@ -38,7 +38,7 @@ are working from a properly configured development environment. Make sure translation requirements are installed in your environment: ```bash -pip install 'mkdocs[i18n]' +pip install 'properdocs[i18n]' ``` [babel]: https://babel.pocoo.org/en/latest/cmdline.html @@ -54,9 +54,9 @@ translation by following the steps below. Here is a quick summary of what you'll need to do: -1. [Fork and clone the MkDocs repository](#fork-and-clone-the-mkdocs-repository) and then [install MkDocs for development](../about/contributing.md#installing-for-development) for adding and testing translations. +1. [Fork and clone the ProperDocs repository](#fork-and-clone-the-properdocs-repository) and then [install ProperDocs for development](../about/contributing.md#installing-for-development) for adding and testing translations. 2. [Initialize new localization catalogs](#initializing-the-localization-catalogs) for your language (if a translation for your locale already exists, follow the instructions for [updating theme localization files](#updating-the-translation-catalogs) instead). -3. [Add a translation](#translating-the-mkdocs-themes) for every text placeholder in the localized catalogs. +3. [Add a translation](#translating-the-properdocs-themes) for every text placeholder in the localized catalogs. 4. [Locally serve and test](#testing-theme-translations) the translated themes for your language. 5. [Update the documentation](#updating-theme-documentation) about supported translations for each translated theme. 6. [Contribute your translation](#contributing-translations) through a Pull Request. @@ -70,13 +70,13 @@ use of a term which differs from the general language translation. [ISO-639-1]: https://en.wikipedia.org/wiki/ISO_639-1 -### Fork and clone the MkDocs repository +### Fork and clone the ProperDocs repository -In the following steps you'll work with a fork of the MkDocs repository. Follow -the instructions for [forking and cloning the MkDocs +In the following steps you'll work with a fork of the ProperDocs repository. Follow +the instructions for [forking and cloning the ProperDocs repository](../about/contributing.md#installing-for-development). -To test the translations you also need to [install MkDocs for +To test the translations you also need to [install ProperDocs for development](../about/contributing.md#installing-for-development) from your fork. ### Initializing the localization catalogs @@ -104,21 +104,21 @@ In particular, the way to know that the `pt` language should be disambiguated as So, if we pick `es` (Spanish) as our example language code, to add a translation for it to both built-in themes, run these commands: ```bash -pybabel init --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l es -pybabel init --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l es +pybabel init --input-file properdocs/themes/mkdocs/messages.pot --output-dir properdocs/themes/mkdocs/locales -l es +pybabel init --input-file properdocs/themes/readthedocs/messages.pot --output-dir properdocs/themes/readthedocs/locales -l es ``` The above command will create a file structure as follows: ```text -mkdocs/themes/mkdocs/locales +properdocs/themes/mkdocs/locales ├── es │   └── LC_MESSAGES │   └── messages.po ``` You can now move on to the next step and [add a -translation](#translating-the-mkdocs-themes) for every text placeholder in the +translation](#translating-the-properdocs-themes) for every text placeholder in the localized catalog. ## Updating a theme translation @@ -128,7 +128,7 @@ since the `messages.po` was last updated for your locale, follow the steps below to update the theme's `messages.po` file: 1. [Update the theme's translation catalog](#updating-the-translation-catalogs) to refresh the translatable text placeholders of each theme. -2. [Translate](#translating-the-mkdocs-themes) the newly added translatable text placeholders on every `messages.po` catalog file language you can. +2. [Translate](#translating-the-properdocs-themes) the newly added translatable text placeholders on every `messages.po` catalog file language you can. 3. [Locally serve and test](#testing-theme-translations) the translated themes for your language. 4. [Contribute your translation](#contributing-translations) through a Pull Request. @@ -141,16 +141,16 @@ for. To update the `fr` translation catalog of both built-in themes, use the following commands: ```bash -pybabel update --ignore-obsolete --input-file mkdocs/themes/mkdocs/messages.pot --output-dir mkdocs/themes/mkdocs/locales -l fr -pybabel update --ignore-obsolete --input-file mkdocs/themes/readthedocs/messages.pot --output-dir mkdocs/themes/readthedocs/locales -l fr +pybabel update --ignore-obsolete --input-file properdocs/themes/mkdocs/messages.pot --output-dir properdocs/themes/mkdocs/locales -l fr +pybabel update --ignore-obsolete --input-file properdocs/themes/readthedocs/messages.pot --output-dir properdocs/themes/readthedocs/locales -l fr ``` You can now move on to the next step and [add a translation] for every updated text placeholder in the localized catalog. -[add a translation]: #translating-the-mkdocs-themes +[add a translation]: #translating-the-properdocs-themes -### Translating the MkDocs themes +### Translating the ProperDocs themes Now that your localized `messages.po` files are ready, all you need to do is add a translation in each `msgstr` item for each `msgid` item in the file. @@ -174,14 +174,14 @@ files of your theme into `messages.mo` files. The following commands will compil the `es` translation for both built-in themes: ```bash -pybabel compile --statistics --directory mkdocs/themes/mkdocs/locales -l es -pybabel compile --statistics --directory mkdocs/themes/readthedocs/locales -l es +pybabel compile --statistics --directory properdocs/themes/mkdocs/locales -l es +pybabel compile --statistics --directory properdocs/themes/readthedocs/locales -l es ``` The above command results in the following file structure: ```text -mkdocs/themes/mkdocs/locales +properdocs/themes/mkdocs/locales ├── es │   └── LC_MESSAGES │   ├── messages.mo @@ -200,7 +200,7 @@ theme: locale: es ``` -Finally, run `mkdocs serve` to check out your new localized version of the theme. +Finally, run `properdocs serve` to check out your new localized version of the theme. > NOTE: > The build and release process takes care of compiling and distributing diff --git a/docs/getting-started.md b/docs/getting-started.md index 490b95d9..0c70b3ca 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,4 +1,4 @@ -# Getting Started with MkDocs +# Getting Started with ProperDocs An introductory tutorial! @@ -6,10 +6,10 @@ An introductory tutorial! ## Installation -To install MkDocs, run the following command from the command line: +To install ProperDocs, run the following command from the command line: ```bash -pip install mkdocs +pip install properdocs ``` For more details, see the [Installation Guide]. @@ -20,26 +20,26 @@ Getting started is super easy. To create a new project, run the following command from the command line: ```bash -mkdocs new my-project +properdocs new my-project cd my-project ``` Take a moment to review the initial project that has been created for you. -![The initial MkDocs layout](img/initial-layout.png) +![The initial ProperDocs layout](img/initial-layout.png) There's a single configuration file named `mkdocs.yml`, and a folder named `docs` that will contain your documentation source files (`docs` is the default value for the [docs_dir] configuration setting). Right now the `docs` folder just contains a single documentation page, named `index.md`. -MkDocs comes with a built-in dev-server that lets you preview your documentation +ProperDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` -configuration file, and then start the server by running the `mkdocs serve` +configuration file, and then start the server by running the `properdocs serve` command: ```console -$ mkdocs serve +$ properdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.22 seconds @@ -50,7 +50,7 @@ INFO - [15:50:43] Serving on http://127.0.0.1:8000/ Open up in your browser, and you'll see the default home page being displayed: -![The MkDocs live server](img/screenshot.png) +![The ProperDocs live server](img/screenshot.png) The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme @@ -130,12 +130,12 @@ Save your changes, and you'll see the ReadTheDocs theme being used. ## Changing the Favicon Icon -By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create +By default, ProperDocs uses the [ProperDocs favicon] icon. To use a different icon, create an `img` subdirectory in the `docs` directory and copy your custom `favicon.ico` -file to that directory. MkDocs will automatically detect and use that file as your +file to that directory. ProperDocs will automatically detect and use that file as your favicon icon. -[MkDocs favicon]: img/favicon.ico +[ProperDocs favicon]: img/favicon.ico ## Building the site @@ -143,7 +143,7 @@ That's looking good. You're ready to deploy the first pass of your `MkLorum` documentation. First build the documentation: ```bash -mkdocs build +properdocs build ``` This will create a new directory, named `site`. Take a look inside the @@ -152,13 +152,13 @@ directory: ```console $ ls site about fonts index.html license search.html -css img js mkdocs sitemap.xml +css img js properdocs sitemap.xml ``` Notice that your source documentation has been output as two HTML files named `index.html` and `about/index.html`. You also have various other media that's been copied into the `site` directory as part of the documentation theme. You -even have a `sitemap.xml` file and `mkdocs/search_index.json`. +even have a `sitemap.xml` file and `properdocs/search_index.json`. If you're using source code control such as `git` you probably don't want to check your documentation builds into the repository. Add a line containing @@ -177,7 +177,7 @@ There are various other commands and options available. For a complete list of commands, use the `--help` flag: ```bash -mkdocs --help +properdocs --help ``` To view a list of options available on a given command, use the `--help` flag @@ -185,7 +185,7 @@ with that command. For example, to get a list of all options available for the `build` command run the following: ```bash -mkdocs build --help +properdocs build --help ``` ## Deploying @@ -198,16 +198,16 @@ you're done. For specific instructions on a number of common hosts, see the ## Getting help -See the [User Guide] for more complete documentation of all of MkDocs' features. +See the [User Guide] for more complete documentation of all of ProperDocs' features. -To get help with MkDocs, please use the [GitHub discussions] or [GitHub issues]. +To get help with ProperDocs, please use the [GitHub discussions] or [GitHub issues]. [Installation Guide]: user-guide/installation.md [docs_dir]: user-guide/configuration.md#docs_dir [deploy]: user-guide/deploying-your-docs.md [nav]: user-guide/configuration.md#nav -[GitHub discussions]: https://github.com/mkdocs/mkdocs/discussions -[GitHub issues]: https://github.com/mkdocs/mkdocs/issues +[GitHub discussions]: https://github.com/properdocs/properdocs/discussions +[GitHub issues]: https://github.com/properdocs/properdocs/issues [site_name]: user-guide/configuration.md#site_name [theme]: user-guide/configuration.md#theme [User Guide]: user-guide/README.md diff --git a/docs/hooks.py b/docs/hooks.py index 15e52dbb..44f2082e 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -5,8 +5,8 @@ from typing import TYPE_CHECKING if TYPE_CHECKING: - from mkdocs.config.defaults import MkDocsConfig - from mkdocs.structure.nav import Page + from properdocs.config.defaults import ProperDocsConfig + from properdocs.structure.nav import Page def _get_language_of_translation_file(path: Path) -> str: @@ -17,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) -> str | None: +def on_page_markdown(markdown: str, page: Page, config: ProperDocsConfig, **kwargs) -> str | None: if page.file.src_uri == 'user-guide/choosing-your-theme.md': here = Path(config.config_file_path).parent diff --git a/docs/img/plugin-events.py b/docs/img/plugin-events.py index 0ad1f982..e032ee8d 100644 --- a/docs/img/plugin-events.py +++ b/docs/img/plugin-events.py @@ -7,7 +7,7 @@ from graphviz import Digraph -graph = Digraph("MkDocs", format="svg") +graph = Digraph("ProperDocs", format="svg") graph.attr(compound="true", bgcolor="transparent") graph.graph_attr.update(fontname="inherit", tooltip=" ") graph.node_attr.update(fontname="inherit", tooltip=" ", style="filled") diff --git a/docs/img/plugin-events.svg b/docs/img/plugin-events.svg index 6fc4702b..d9d42df1 100644 --- a/docs/img/plugin-events.svg +++ b/docs/img/plugin-events.svg @@ -1,7 +1,7 @@ -MkDocs +ProperDocs diff --git a/docs/index.md b/docs/index.md index f796a054..de0b1654 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,10 @@ -# MkDocs +# ProperDocs Project documentation with Markdown. --- -MkDocs is a **fast**, **simple** and **downright gorgeous** static site +ProperDocs is a **fast**, **simple** and **downright gorgeous** static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the [introductory tutorial], then check the @@ -27,13 +27,13 @@ configuration file. Start by reading the [introductory tutorial], then check the

Great themes available

- There's a stack of good looking themes available for MkDocs. + There's a stack of good looking themes available for ProperDocs. Choose between the built in themes: mkdocs and readthedocs, select one of the third-party themes - (on the MkDocs Themes wiki page - as well as the MkDocs Catalog), + (on the ProperDocs Themes wiki page + as well as the ProperDocs Catalog), or build your own.

@@ -77,7 +77,7 @@ configuration file. Start by reading the [introductory tutorial], then check the

Host anywhere

- MkDocs builds completely static HTML sites that you can host on + ProperDocs builds completely static HTML sites that you can host on GitHub Pages, Amazon S3, or anywhere else you choose. diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md index aea3ba83..65b7859d 100644 --- a/docs/user-guide/README.md +++ b/docs/user-guide/README.md @@ -1,10 +1,10 @@ # User Guide -Building Documentation with MkDocs +Building Documentation with ProperDocs --- -The MkDocs User Guide provides documentation for users of MkDocs. See +The ProperDocs User Guide provides documentation for users of ProperDocs. See [Getting Started] for an introductory tutorial. You can jump directly to a page listed below, or use the *next* and *previous* buttons in the navigation bar at the top of the page to move through the documentation in order. diff --git a/docs/user-guide/choosing-your-theme.md b/docs/user-guide/choosing-your-theme.md index 92d0eb65..210d0450 100644 --- a/docs/user-guide/choosing-your-theme.md +++ b/docs/user-guide/choosing-your-theme.md @@ -4,7 +4,7 @@ Selecting and configuring a theme. --- -MkDocs includes two built-in themes ([mkdocs](#mkdocs) and +ProperDocs includes two built-in themes ([mkdocs](#mkdocs) and [readthedocs](#readthedocs)), as documented below. However, many [third party themes] are available to choose from as well. @@ -19,7 +19,7 @@ theme: ## mkdocs The default theme, which was built as a custom [Bootstrap] theme, supports almost -every feature of MkDocs. +every feature of ProperDocs.