All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
0.22.0 - 2023-05-25
- Report inventory loading errors (2c05d78 by Timothée Mazzucotelli). Co-authored-by: Oleh Prypin oleh@pryp.in
0.21.2 - 2023-04-06
- Fix regression with LRU cached method (85efbd2 by Timothée Mazzucotelli). Issue #549
0.21.1 - 2023-04-05
- Fix missing typing-extensions dependency on Python less than 3.10 (bff760b by Timothée Mazzucotelli). Issue #548
0.21.0 - 2023-04-05
- Expose the full config to handlers (15dacf6 by David Patterson). Issue #501, PR #509
0.20.0 - 2023-01-19
- Add
enabledconfiguration option (8cf117d by StefanBRas). Issue #478, PR #504
- Handle updating Jinja environment of multiple handlers (a6ea80c by David Patterson). Related PR #201, Issue #502, PR #507
- Make
_load_inventoryaccept lists as arguments (105ed82 by Sorin Sbarnea). Needed by PR mkdocstrings/python#49, PR #511 - Remove support for MkDocs < 1.2 (we already depended on MkDocs >= 1.2) (ac963c8 by Timothée Mazzucotelli).
0.19.1 - 2022-12-13
- Fix regular expression for Sphinx inventory parsing (348bdd5 by Luis Michaelis). Issue #496, PR #497
- Small fixes to type annotations (9214b74 by Oleh Prypin). PR #470
- Report usage-based warnings as user-facing messages (03dd7a6 by Oleh Prypin). PR #464
0.19.0 - 2022-05-28
We decided to deprecate a few things to pave the way towards a more stable code base, bringing us closer to a v1.
- Selection and rendering options are now combined into a single
optionskey. Using the old keys will emit a deprecation warning. - The
BaseCollectorandBaseRendererclasses are deprecated in favor ofBaseHandler, which merges their functionality. Using the old classes will emit a deprecation warning.
New versions of the Python handler and the legacy Python handler
were also released in coordination with mkdocstrings 0.19.
See their respective changelogs:
python,
python-legacy.
Most notably, the Python handler gained the members and filters options
that prevented many users to switch to it.
mkdocstrings stopped depending directly on the legacy Python handler. It means you now have to explicitely depend on it, directly or through the extra provided by mkdocstrings, if you want to continue using it.
- Stop depending directly on mkdocstrings-python-legacy (9055d58 by Timothée Mazzucotelli). Issue #376
- Pass config file path to handlers (cccebc4 by Timothée Mazzucotelli). Issue #311, PR #425
- Support options / deprecated options mix-up (7c71f26 by Timothée Mazzucotelli).
- Deprecate watch feature in favor of MkDocs' built-in one (c20022e by Timothée Mazzucotelli).
- Log relative template paths if possible, instead of absolute (91f5f83 by Timothée Mazzucotelli).
- Deprecate
selectionandrenderingYAML keys (3335310 by Timothée Mazzucotelli). PR #420 - Deprecate
BaseCollectorandBaseRenderer(eb822cb by Timothée Mazzucotelli). PR #413
0.18.1 - 2022-03-01
- Don't preemptively register identifiers as anchors (c7ac043 by Timothée Mazzucotelli).
0.18.0 - 2022-02-06
- Python 3.6 support is dropped.
- We provide a new, experimental Python handler based on Griffe.
This new handler brings automatic cross-references for every annotation in your code,
including references to third-party libraries' APIs if they provide objects inventories
and you explicitely load them in
mkdocs.yml. See migration notes in the documentation. - The "legacy" Python handler now lives in its own repository at https://github.com/mkdocstrings/python-legacy.
- Add Crystal extra, update Python extras versions (b8222b0 by Timothée Mazzucotelli). PR #374
- Update autorefs to actually required version (fc6c7f6 by Timothée Mazzucotelli).
- Drop Python 3.6 support (7205ac6 by Timothée Mazzucotelli).
- Allow unwrapping the
<p>tag inconvert_markdownfilter (5351fc8 by Oleh Prypin). PR #369 - Support handlers spanning multiple locations (f42dfc6 by Timothée Mazzucotelli). PR #355
- Prefix logs with the package name only (6c2b734 by Timothée Mazzucotelli). PR #375
- Extract the Python handler into its own repository (74371e4 by Timothée Mazzucotelli). PR #356
- Support Jinja2 3.1 (b377227 by Timothée Mazzucotelli). Issue #360, PR #361
- Find templates in new and deprecated namespaces (d5d5f18 by Timothée Mazzucotelli). PR #367
- Support loading handlers from the
mkdocstrings_handlersnamespace (5c22c6c by Timothée Mazzucotelli). PR #367
0.17.0 - 2021-12-27
- Add
show_signaturerendering option (024ee82 by Will Da Silva). Issue #341, PR #342 - Support Keyword Args and Yields sections (1286427 by Timothée Mazzucotelli). Issue #205 and #324, PR #331
- Do minimum work when falling back to re-collecting an object to get its anchor (f6cf570 by Timothée Mazzucotelli). Issue #329, PR #330
- Return multiple identifiers from fallback method (78c498c by Timothée Mazzucotelli). Issue mkdocstrings/autorefs#11, PR #350
0.16.2 - 2021-10-04
0.16.1 - 2021-09-23
- Fix ReadTheDocs "return" template (598621b by Timothée Mazzucotelli).
0.16.0 - 2021-09-20
- Add a rendering option to change the sorting of members (b1fff8b by Joe Rickerby). Issue #114, PR #274
- Add option to show Python base classes (436f550 by Brian Koropoff). Issue #269, PR #297
- Support loading external Python inventories in Sphinx format (a8418cb by Oleh Prypin). PR #287
- Support loading external inventories and linking to them (8b675f4 by Oleh Prypin). PR #277
- Very basic support for MkDocs theme (974ca90 by Oleh Prypin). PR #272
- Generate objects inventory (14ed959 and bbd85a9 by Timothée Mazzucotelli). Issue #251, PR #253
- Don't render empty code blocks for missing type annotations (d2e9e1e by Oleh Prypin).
- Fix custom handler not being used (6dcf342 by Timothée Mazzucotelli). Issue #259, PR #263
- Don't hide
setup_commandserrors (92418c4 by Gabriel Vîjială). PR #258
0.15.2 - 2021-06-09
- MkDocs default schema needs to be obtained differently now (b3e122b by Oleh Prypin). PR #273
- Compatibility with MkDocs 1.2: livereload isn't guaranteed now (36e8024 by Oleh Prypin). PR #294
0.15.1 - 2021-05-16
- Prevent error during parallel installations (fac2c71 by Timothée Mazzucotelli).
- Support the upcoming major Jinja and MarkupSafe releases (bb4f9de by Oleh Prypin). PR #283
- Accept a higher version of mkdocs-autorefs (c8de08e by Oleh Prypin). PR #282
0.15.0 - 2021-02-28
The following items are possible breaking changes:
- Cross-linking to arbitrary headings now requires to opt-in to the autorefs plugin, which is installed as a dependency of mkdocstrings. See Cross-references to any Markdown heading.
- mkdocstrings now respects your configured code highlighting method,
so if you are using the CodeHilite extension, the
.highlightCSS class in the rendered HTML will become.codehilite. So make sure to adapt your extra CSS accordingly. Or just switch to using pymdownx.highlight, it's better supported by mkdocstrings anyway. See Syntax highlighting. - Most of the CSS rules that mkdocstrings used to recommend for manual addition, now become mandatory (auto-injected into the site). This shouldn't break any of your styles, but you are welcome to remove the now-redundant lines that you had copied into
extra_css, similarly to this diff.
- Nicer-looking error outputs - no tracebacks from mkdocstrings (6baf720 by Oleh Prypin). PR #230
- Let handlers add CSS to the pages, do so for Python handler (05c7a3f by Oleh Prypin). Issue #189, PR #218
- Allow linking to an object heading not only by its canonical identifier, but also by its possible aliases (4789950 by Oleh Prypin). PR #217
- Propagate the CSS class to inline highlighting as well (c7d80e6 by Oleh Prypin). PR #245
- Don't double-escape characters in highlighted headings (6357144 by Oleh Prypin). Issue #228, PR #241
- Use the autorefs plugin from its new external location (e2d74ef by Oleh Prypin). PR #235
- Split out Markdown extensions from
handlerstohandlers.rendering(7533852 by Oleh Prypin). PR #233 - Theme-agnostic code highlighting, respecting configs (f9ea009 by Oleh Prypin). PR #202
- Split out autorefs plugin, make it optional (fc67656 by Oleh Prypin). PR #220
- Remove the extra wrapper div from the final doc (7fe438c by Oleh Prypin). PR #209
- Don't re-parse the whole subdoc, expose only headings (15f84f9 by Oleh Prypin). PR #209
- Actually exclude hidden headings from the doc (0fdb082 by Oleh Prypin). PR #209
0.14.0 - 2021-01-06
Special thanks to Oleh @oprypin Prypin who did an amazing job (this is a euphemism) at improving mkdocstrings, fixing hard-to-fix bugs with clever solutions, implementing great new features and refactoring the code for better performance and readability! Thanks Oleh!
- Fix double code tags (e84d401 by Timothée Mazzucotelli).
- Don't mutate the original Markdown config for permalinks (8f6b163 by Oleh Prypin).
- Preserve text immediately before an autodoc (07466fa by Oleh Prypin). PR #207
- Remove
hrefattributes from headings in templates (d5602ff by Oleh Prypin). PR #204 - Don't let
tocextension append its permalink twice (a154f5c by Oleh Prypin). PR #203 - Fix undefined entity for
¶(2c29211 by Timothée Mazzucotelli). - Make ids of Markdown sub-documents prefixed with the parent item id (d493d33 by Oleh Prypin). Issue #186 and #193, PR #199
- More lenient regex for data-mkdocstrings-identifier (dcfec8e by Oleh Prypin).
- Shift Markdown headings according to the current
heading_level(13f41ae by Oleh Prypin). Issue #192, PR #195 - Fix footnotes appearing in all following objects (af24bc2 by Oleh Prypin). Issue #186, PR #195
- Fix cross-references from the root index page (9c9f2a0 by Oleh Prypin). Issue #184, PR #185
- Fix incorrect argument name passed to Markdown (10ce502 by Timothée Mazzucotelli).
- Fix error when a digit immediately follows a code tag (9b92341 by Oleh Prypin). Issue #169, PR #175
- Detecting paths relative to template directory in logging (a50046b by Oleh Prypin). Issue #166
- BlockProcessor already receives strings, use them as such (bcf7da9 by Oleh Prypin).
- Remove some unused code (8504084 by Oleh Prypin). PR #206
- Improve XML parsing error handling (ad86410 by Timothée Mazzucotelli).
- Explicitly use MarkupSafe (6b9ebe7 by Oleh Prypin).
- Split out the handler cache, expose it through the plugin (6453026 by Oleh Prypin). Issue #179, PR #191
- Use ChainMap instead of copying dicts (c634d2c by Oleh Prypin). PR #171
- Rename logging to loggers to avoid confusion (7a119cc by Timothée Mazzucotelli).
- Simplify logging (409f93e by Timothée Mazzucotelli).
- Allow specifying
heading_levelas a Markdown heading (10efc28 by Oleh Prypin). PR #170 - Allow any characters in identifiers (7ede68a by Oleh Prypin). PR #174
- Allow namespace packages for handlers (39b0465 by Timothée Mazzucotelli).
- Add template debugging/logging (33b32c1 by Timothée Mazzucotelli).
- Add initial support for the ReadTheDocs theme (1028115 by Timothée Mazzucotelli). Issue #107, PR #159
- Add option to show type annotations in signatures (f94ce9b by Timothée Mazzucotelli). Issue #106
- Accept verions of
pytkdocsup to 0.10.x (see changelog).
- Call
update_envonly once perMarkdowninstance (b198c74 by Oleh Prypin). PR #201 - Disable Jinja's
auto_reloadto reduce disk reads (3b28c58 by Oleh Prypin). PR #200 - Rework autorefs replacement to not re-parse the final HTML (22a9e4b by Oleh Prypin). Issue #187, PR #188
0.13.6 - 2020-09-28
0.13.5 - 2020-09-28
- Accept
pytkdocsversion up to 0.9.x (changelog).
0.13.4 - 2020-09-25
0.13.3 - 2020-09-25
- Accept
pytkdocsversion up to 0.8.x (changelog).
0.13.2 - 2020-09-08
- Fix relative URLs when
use_directory_urlsis false (421d189 by Timothée Mazzucotelli). References: #149
0.13.1 - 2020-09-03
0.13.0 - 2020-08-21
- Add option to show full path of direct members only (d1b9401 by Aaron Dunmore). References: #134, #136
- Accept
pymdown-extensionsversions up to 0.8.x (see release notes) (178d48d by Hugo van Kemenade). PR #146
0.12.2 - 2020-07-24
- Accept
pytkdocsversion up to 0.7.x (changelog).
0.12.1 - 2020-07-07
- Fix HTML-escaped sequence parsing as XML (db297f1 by Timothée Mazzucotelli).
- Allow running mkdocs from non-default interpreter (283dd7b by Jared Khan).
0.12.0 - 2020-06-14
- Support attributes section in Google-style docstrings (8300253 by Timothée Mazzucotelli). References: #88
- Support examples section in Google-style docstrings (650c754 by Iago González). References: #112
- Accept
pytkdocsversion up to 0.6.x (changelog).
0.11.4 - 2020-06-08
- Accept
pytkdocsversion up to 0.5.x (changelog). If it breaks your docs, please open issues onpytkdocs' bug-tracker, or pinpytkdocsversion to while waiting for bug fixes <0.5.0 :clown:.
0.11.3 - 2020-06-07
0.11.2 - 2020-05-20
- Increase
pytkdocsversion range to accept 0.4.0 (changelog).
0.11.1 - 2020-05-14
- Fix integration with mkdocs logging une bonne fois pour toute (3293cbf by Timothée Mazzucotelli).
- Discard setup commands stdout (ea44cea by Timothée Mazzucotelli). References: #91
- Use the proper python executable to start subprocesses (9fe3b39 by Reece Dunham). References: #91, #103
0.11.0 - 2020-04-23
- Properly raise on errors (respect strict mode) (2097208 by Timothée Mazzucotelli). Related issues/PRs: #86
- Hook properly to MkDocs logging (b23daed by Timothée Mazzucotelli). Related issues/PRs: #86
- Add
setup_commandsoption to python handler (599f8e5 by Ross Mechanic). Related issues/PRs: #89, #90 - Add option to allow overriding templates (7360021 by Mikaël Capelle). Related issues/PRs: #59, #82
0.10.3 - 2020-04-10
This version increases the accepted range of versions for the pytkdocs dependency to >=0.2.0, <0.4.0.
The pytkdocs project just released version 0.3.0
which:
- adds support for complex markup in docstrings sections items descriptions
- adds support for different indentations in docstrings sections (tabulations or less/more than 4 spaces)
- fixes docstring parsing for arguments whose names start with
*, like*argsand**kwargs
0.10.2 - 2020-04-07
This version increases the accepted range of versions for the pymdown-extensions dependency,
as well as for the mkdocs-material development dependency. Indeed, both these projects recently
released major versions 7 and 5 respectively. Users who wish to use these new versions will be able to.
See issue #74.
0.10.1 - 2020-04-03
- Fix jinja2 error for jinja2 < 2.11 (387f970 by Timothée Mazzucotelli). Related issues/PRs: #67, #72
- Fix missing dependency pymdown-extensions (648b99d by Timothée Mazzucotelli). Related issues/PRs: #66
- Fix heading level of hidden toc entries (475cc62 by Timothée Mazzucotelli). Related issues/PRs: #65
- Fix rendering signatures containing keyword_only (c6c5add by Timothée Mazzucotelli). Related issues/PRs: #68
0.10.0 - 2020-03-27
- Prepare for new
pytkdocsversion (336421a). Add optionsfiltersandmembersto the Python collector to reflect the newpytkdocsoptions. See the default configuration of the Python collector.
0.9.1 - 2020-03-21
- Fix cross-references when deploying to GitHub pages (36f804b).
0.9.0 - 2020-03-21
This version is a big refactor. We will just list the new features without pointing to particular commits. The documentation rendering looks slightly different, and should be better than before. No identified breaking changes for end-users.
- Language agnostic: we moved the code responsible for loading Python documentation into a new project,
pytkdocs, and implemented a "handlers" logic, effectively allowing to support any given language. Waiting for your handlers contributions 😉! - Multiple themes support: handlers can offer templates for multiple
mkdocsthemes. - Better cross-references: cross-references now not only work between documented objects (between all languages, given the objects' identifiers are unique), but also for every heading of your Markdown pages.
- Configuration options: the rendering of Python documentation can now be configured, (globally and locally thanks to the handlers system), check the docs! Also see the recommended CSS.
- Proper logging messages:
mkdocstringsnow logs debug, warning and error messages, useful when troubleshooting.
- Various fixes and better error handling.
0.8.0 - 2020-03-04
- Be compatible with Mkdocs >= 1.1 (5a974a4). This is a breaking change as we're not compatible with versions of Mkdocs below 1.1 anymore. If you cannot upgrade Mkdocs to 1.1, pin mkdocstrings' version to 0.7.2.
0.7.2 - 2020-03-04
- Catch
OSErrorwhen trying to get source lines (8e8d604). - Do not render signature empty sentinel (16dfd73).
- Fix for nested classes and their attributes (7fef903).
- Fix
relative_file_pathmethod (52715ad). - Wrap file path in backticks to escape it (2525f39).
0.7.1 - 2020-02-18
- Replace literal slash with os.sep for Windows compatibility (70f9af5).
0.7.0 - 2020-01-13
- Don't guess lang in generated docs (db4f60a).
- Render at HTML step with custom markdown converter (9b5a3e1).
- Change forward ref to ref, fix optional unions (2f0bfaa).
- Discover package submodules (231062a).
- Implement watched source code (hacks) (4a67953).
0.6.1 - 2020-01-02
- Break docstring discarding loop if found (5a17fec).
- Fix discarding docstring (143f7cb).
- Fix getting annotation from nodes (ecde72b).
- Fix various things (affbf06).
- Break as soon as we find the same attr in a parent class while trying to discard the docstring (65d7908).
- Split Docstring.parse method to improve readability (2226e2d).
0.6.0 - 2019-12-28
- Fix GenericMeta import error on Python 3.7+ (febf2b9).
- More classes. Still ugly code though :'( (f41c119).
- Split into more modules (f1872a4).
- Use Object subclasses (40dd106).
0.5.0 - 2019-12-22
- Use divs in HTML contents to ease styling (2a36a0e).
0.4.0 - 2019-12-22
- Parse docstrings Google-style blocks, get types from signature (5af0c7b).
0.3.0 - 2019-12-21
- Allow object referencing in docstrings (2dd50c0).
0.2.0 - 2019-12-15
- Refactor, features, etc. (111fa85).