GithubHelp home page GithubHelp logo

mkdocs / get-deps Goto Github PK

View Code? Open in Web Editor NEW
1.0 5.0 0.0 27 KB

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

License: MIT License

Shell 1.43% Python 98.57%

get-deps's Introduction

mkdocs-get-deps

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

PyPI License GitHub Workflow Status

Installation:Alternatively through MkDocs itself:
pip install mkdocs-get-deps
pip install mkdocs

This command guesses the Python dependencies that a MkDocs site requires in order to build. It simply prints the PyPI packages that need to be installed. In the terminal it can be combined directly with a pip install command, as per the last example below:

Usage:Alternatively through MkDocs itself:
# Print dependencies of the current project
mkdocs-get-deps
# Save them into a file
mkdocs-get-deps > requirements.txt
# Install dependencies on the fly
pip install $(mkdocs-get-deps)
mkdocs get-deps

mkdocs get-deps > requirements.txt
pip install -r requirements.txt

pip install $(mkdocs get-deps)

The idea is that right after running this command, you can directly follow it up with mkdocs build and it will almost always "just work", without needing to think which dependencies to install.

The way it works is by scanning mkdocs.yml for themes:, plugins:, markdown_extensions: items and doing a reverse lookup based on a large list of known projects (catalog, see below).

Of course, you're encouraged 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.

MkDocs' official catalog of plugins

Check out https://github.com/mkdocs/catalog and add all your general-purpose plugins, themes and extensions there, so that they can be looked up through mkdocs get-deps.

get-deps's People

Contributors

oprypin avatar

Stargazers

 avatar

Watchers

 avatar  avatar  avatar  avatar  avatar

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]

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.