mkdocs / get-deps

An extra command for MkDocs that infers required PyPI packages from `plugins` in mkdocs.yml

MkDocs

Project documentation with Markdown

MkDocs 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 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 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!

• For questions and high-level discussions, use Discussions on GitHub.
  • For small questions, a good alternative is the Chat room on Gitter/Matrix.
• 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 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.

Make sure to stick around to answer some questions as well!

Links

• Official Documentation
• Latest Release Notes
• Catalog of third-party plugins, themes and recipes

Contributing to MkDocs

The MkDocs 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 discussion forums is expected to follow the PyPA Code of Conduct.

License

BSD-2-Clause

get-deps's Issues

Extra dependencies conditioned by configuration values

Currently, in the catalog, we have this entry for mkdocstrings:

- name: mkdocstrings
  mkdocs_plugin: mkdocstrings
  extra_dependencies:
    plugins.mkdocstrings.handlers.crystal: mkdocstrings-crystal
    plugins.mkdocstrings.handlers.python: mkdocstrings-python
  github_id: mkdocstrings/mkdocstrings
  pypi_id: mkdocstrings
  labels: [plugin]
  category: api-docs

The extra dependencies config means that if we find a plugins.mkdocstrings.handlers.crystal key in the config, mkdocstrings-crystal should be installed, etc..

Two other examples:

# markdown-exec entry
extra_dependencies:
  plugins.markdown-exec.ansi: markdown-exec[ansi]

# mkdocs-material entry
extra_dependencies:
  plugins.social: mkdocs-material[imaging]

Here we use the same mechanism to list extras.

However in the second example (markdown-exec), the extra should actually be conditioned by the value of the plugins.markdown-exec.ansi config: markdown-exec supports values "required", "off", "auto", true and false (and other YAML boolean variants). The [ansi] extra should only be listed when the value is "required" or true (with "auto", which is the default value, we suppose that users are not aware of the ANSI feature and do not use it).

What I suggest is that we allow to specify the values that condition the addition of extra dependencies, something like:

extra_dependencies:
  plugins.markdown-exec.ansi:
    required: markdown-exec[ansi]
    true: markdown-exec[ansi]

Such a feature will also be useful for inferring extra dependencies needed when two specific config values are found. For example, in mkdocstrings-python we may want to decouple templates from the Python code (see mkdocstrings/python#152). In that case, we would want get-deps to infer that mkdocstrings-python-material is needed when both the plugins.mkdocstrings.handlers.python is found and the theme.name value is equal to "material". In that case though we need a yet more complex syntax, of which I'm still unsure 🤔:

extra_dependencies:
  # possible extra dependency mkdocstrings-python-material installed when...
  mkdocstrings-python-material:
    # ...the plugins.mkdocstrings.handlers.python key is present
    - plugins.mkdocstrings.handlers.python
    # ...and when the theme.name value is equal to "material"
    - theme.name: material 

Notice how the key and values were reversed here, compared to the previous example and current behavior. Maybe we can reverse the previous suggestion too?

extra_dependencies:
  # possible extra dependency markdown-exec[ansi] installed when...
  markdown-exec[ansi]:
    # ...the plugins.markdown-exec.ansi value is equal to...
    - plugins.markdown-exec.ansi:
      # ...either "required" or true
      - required
      - true

Note how in the mkdocstrings case, the dependency conditions are AND'ed, and in the markdown-exec case, condition values are OR'ed. Both cases are compatible. Example using both:

extra_dependencies:
  # possible extra dependency foo installed when...
  foo:
    # ...the extra.bar key is present
    - extra.bar
    # ...and the extra.baz value is equal to 1, 2, or 3...
    - extra.baz: [1, 2, 3]
    # ...and the extra.qux value is present or equal to foo
    - extra.qux: [null, foo]