New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Plugin API. #206
Comments
So, I'm generally +1 on the 'plugin architecture' idea. It's something I have been pondering a bit. |
Awesome, is that something that you guys have a plan/roadmap for? Do you need help implementing? |
I'll probably have to deferr to @tomchristie for this. However, it is something that I do think it a good idea and I would like to see. To make MkDocs work for more people and in more situations we should allow them to be able to extend it. This does however go against a few of the goals:
I'm sure I had a third in mind but I can't think of it now. |
Certainly be interesting to see someone work on this, but I'd be wary of pulling anything in when there's still a bunch of work ahead in order to get to a solid 1.0 release. What would be most likely to convince me on something like this would be documentation pull requests that demonstrate the API design work, and show exactly how these plugins would work from a user perspective. Personally I think we're probably still too early in the day to start thinking about maintaince-increasing features like a plugin architecture, but that's not to say that I wouldn't be interested in seeing how it might be tackled. |
I think we can work towards it by defining the build pipeline better and exposing API's to use internally (at first). Internal only use means we don't need to worry even slightly about supporting external plugins until it settles. I have been working on support for local searching which requires a few things: The search index needs to be created during the page builds, I need to figure out if the theme supports it (by looking for the js lib, I think, not sure yet) and probably some other stuff. To make this work I need to hook into the process in a number of places, doing this manually is a bit nasty and each section is slowly getting more complicated. tl;dr - improving the abractions and build processes internally would make it much easier to support a plugin api and add other features we do want to support in core. |
All sounds reasonable. |
I would use a plugin API that allows us to add pre and post process steps, for brute force changes (though given the experience we have with TWiki/Foswiki, I would also suggest you don't do this. mmmm, actually, the safest thing you could add, would be a mechanism that allows the registration of a contextless markup processing causes much less in the way of lock in - and if you use a pre-built parse tree (ish), you're not totally tied to the original formatting (and can validate too) but it does depend on the cleverness of the parser you use - regexp based ones are generally less robust. |
moby/moby#8976 (comment) is one example, where we really would prefer to have one section of information (what kernel versions and features are needed) be transcluded into many documents. Ideally, I'd use a foswiki style |
…mentation generation for python
I'm not sure if you want me to make a pull request for this, I took a first pass stab at the API architecture + some extensions (autodocumentation + tree heirarchy) https://github.com/ProjexSoftware/mkdocs The new *.md files are the result of the
The
The documentation for the usage of the extensions is within the extensions themselves. The API is just an event system (defined in |
Woah, that's a huge code dump. It looks interesting, but I have a few questions/concerns.
Personally I'd be much more interested in autodoc functionality that enabled me to write prose. I'm not sure how this would work, but I'd expect markers or something in the Markdown that then pull in the relevant functions. So, rather that dumplicating the information in my docs, i write a paragraph and add that will then find and include the method dignature for me. I'm still thinking this idea through tho' |
For this to potentially work, we need to split up the dicsussion. A pull request for the extension API addition and then a pull request each for the potentially included extensions. |
I'm sure. We don't. :) The only thing pulling third party extensions into the core project does is mean that it's suddenly our job to maintain them, instead of the author's. That would suck.
Just the first of those two. Of course we do need to also see something built against that API in order to validate it, but not as a pull request into this project. If MkDocs becomes well adopted, we need to keep the project absolutely as minimal as possible. Focusing on a core, well documented, minimal product, has to be the overriding design choice with anything like this. |
Sure, understood. I cleaned it all up so now only the changes to the core exist in that project and I created a pull request for it. The actual implementation for the extensions I moved to my own repo as public projects: https://github.com/erichulser/mkdocs_autodoc
Works the same way as before, just now they are their own repos. I wrote up a little explanation of the code changes in the pull request that made these possible, and can easily modify as needed once you decide upon a good/acceptable API structure.
This is all my code, but I would give it as a
Yea, no worries -- that was really more just an example of the output.
I can work on things like that -- I've had the opposite need as I'm working on documenting API calls where I don't necessarily expect or want people to have to jump into the code vs. something like this which is more functional usage. The idea being I start with prose, but when I say a "XYZ" class is returned, they can click the link and see what properties are available once they have that object, similar to how Qt's documentation is setup. |
…mentation generation for python
@d0ugal stated above:
Just an FYI, I created a proof-of-concept Markdown Extension that does just that: mddocs. No mkdocs Plugin API required. Just add I mention it here because I think most, if not all, of the proposed reasons for including a Plugin API to mkdocs can be handled by building specific Markdown Extensions. For example, Pelican (a more complex sorta competitor to mkdocs) offers a plugin API and many of their plugins are re-implementing things that Markdown's Extension API already makes possible. The one exception is perhaps related to #144. There would need to be a way to pass some context variables into the Markdown Extension to make them available within the Markdown parser to swap out a placeholder of some kind. It would be easily doable with a Markdown Extension that shipped with mkdocs (perhaps defined in the same namespace as the context), but near impossible with a third party extension without a Plugin API. I didn't look too closely, but does the proposed Plugin API even allow for this use case? |
I'd like to make some programmatic changes (like auto-interlinking with GitHub issues, auto-generating docs for CLI options, etc.) to my docs before they get published. I can write a script to make these changes, but then Since the plugin API doesn't seem to be ready yet, I wanted to ask whether there's any kind of workaround. I'm pretty fluent in Python, but I didn't find any Python API I could hook anything into. |
@honzajavorek there are two ways others have accomplished that. Either run scripts before or after That said, you're not likely to get anything to work with the ReadTheDocs service. As I understand it, they are stuck on MkDocs version 0.14 and their build runs on their servers. In other words, you can't modify their build process or build locally before pushing up to their servers. |
@waylan Thanks for the super-fast and super-useful reply! In that case, I'm probably left either with moving away from RTD (not an easy option at this moment) or switching to Sphinx 😢 (since as far as I understand it, Sphinx should be extensible and RTD should respect that). |
FYI, I have rebased (a copy of) the plugin branch onto the 1.0.dev branch. You can see it here: 1.0.dev...waylan:plugin1.0 |
See the included documentation for a full explaination of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
FYI, I have created a PR for the Plugin API. You can review it in #1223. Any and all feedback welcome. |
See the included documentation for a full explaination of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explaination of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explaination of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explaination of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explaination of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
I've made a Pygments Lexer for API Blueprint (https://github.com/kylef/pygments-apiblueprint) which can be used with mkdocs (see example: apiaryio/dredd#779). |
See the included documentation for a full explanation of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes #206
See the included documentation for a full explanation of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explanation of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explanation of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explanation of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes mkdocs#206
See the included documentation for a full explanation of the API. Search has been removed and wrapped in a plugin (named "legacy_search"). The search feature was ported as-is. None of the open issues with search have been addressed. Presumably, a new search plugin will be built from the ground up which addresses those issues. Note that there is no 'default' plugins. That means that users get no search unless they enable it in the config by adding the following to their `mkdocs.yml` file: plugins: - legacy_search Fixes #206
Hey Tom,
I've worked on my own documentation generator for a while and used that but am in the process of upgrading it, so I wanted to see what was out there besides Sphinx (which is way to bloated). I came across this project and I really like the simplicity of it. One of the requirements I have for documentation is auto-module/class docs as a means to augment the prose style.
I know you've already stated that you have no interest in that, but I was wondering if you'd be interested in allowing me to work with you on this project. I have all the code for generating docs that output a format like the ones used in Qt (http://qt-project.org/doc/qt-4.8/qdialog.html) from the python docs. I would propose simply adding a plugin architecture to mkdocs (similar to django/pyramid) that would allow a developer to run additional addons so as to not pollute the core of the project. Something like:
Where there would be a render hook that would dynamically generate the content from the
my_project
package as markdown files that could be then used and referenced from the prose style. I would be happy to work with you on the structure and provide the work I've been doing for the auto-class documentation as a plugin.Please let me know if this is something that you'd be interested in discussing, otherwise I may end up forking this project and implementing that as an option.
The text was updated successfully, but these errors were encountered: