Move plugin writers guide to template and refactor
The plugin template will house the bulk of the plugin writer docs.
Give plugin writers a base for documentation:¶
Completion of this task will create docs/template/ directories. Overviews and guides should be included in this directory, documentation of what to do with in specific areas of the code should be moved to comments in that code. When running bootstrap.py, docs/* should be included but not docs/template/. The Makefile should work for a bootstrapped plugin.
What should go where:¶
The index of the guide contains some generally useful information outlining what plugins do, this should stay in the pulpcore docs, possibly moved to Plugins index next to the plugin list.
Planning Guide should move to the plugin template docs. Suggest rename to "Overview"
Checklist should be moved to the template docs. It is probably worth separating the checklist into 2 sections. (1) Tasks done by the template and (2) Tasks done by a plugin writer. This way, the plugin writers who use the template will know what was done for them.
Writing Your First Plugin is the narratave documentation, and should be moved to the template. Suggest rename to "Plugin Writing Walkthrough".
- The "Understanding Models" section be replaced with a link to pulpcore's docs/overview/concepts.rst. For concepts not mentioned in the core overview, they should be explained in the steps where they are relevant. For example, RemoteArtifact and PublishedArtifact should be added to the steps for implementing sync and publish.
- Begin with assumed knowledge, at minimum including links to the planning guide and overview/index.rst
- Move the bootstrapping instructions from plugin_template/README to a new section "bootstrapping"
- The rest of the document becomes a TODO list for plugin writers. The specifics should be moved to the relevant modules. Add content for why a plugin writer might need to do this step. It may be possible to combine this with the checklist.
- Pulp Plugin Basics should be combined with the planning guide/overview. "Documenting your API" should be moved to its own section.
- Releasing your plugin should be moved to the plugin template, but does not need to be altered.
- Generating a CLI is a stub, but should be moved to the template, and an issue filed to complete it.
The instructions should be moved into the modules, changing the code is not part of the scope of this task (unless it is incorrect.) Over time working code should be favored, because it can be tested (instructions can't). The comments should explain what the code does and include suggestions for expanding it.
#3 Updated by bmbouter over 3 years ago
I can see how this makes sense to do, but it will create some new challenges, specifically for how we render these docs online. For Pulp3 the current plan is to keep the docs builders really simple and not "combine" multiple sphinx projects or content from multiple repositories at build time the way we did in Pulp2.
How would this transition allow docs to be built and still keep the docs only building from 1 repository?
#4 Updated by email@example.com over 3 years ago
bmbouter, I don't think the plugin writers docs needs to live in the same place as the pulp docs. We could host on rtd, but I don't think its really necessary to host at all. For potential plugin writers gathering research, github rendered rst files will be enough, and anyone who is actually writing a plugin will have the template cloned locally. The plugin writer could be instructed to build the docs themselves or just use the files.
#5 Updated by bmbouter over 3 years ago
I see the docs living on one site as a big benefit. Splitting the docs across two sites seems like a step backwards. This change has benefits, but if that's the cost then I don't think it's something we should do.
The email advertising the changes did say the docs would move, but they also said it would leave high level docs in the existing repo and link to the plugin_template. I was focused on that second statement when I +1'd it, so I didn't think we were moving huge amounts of content.
I think the concern that our documentation would be leaving our docs site needs to be highlighted more clearly for everyone who +1'd this.
As an aside, I believe the plugin_template is not more useful than pulp_file and actually worse. I forked plugin_template into pulp_ansible, and I had to replace the name plugin_template in all the same places I would have replaced pulp_file. plugin_template was even less useful than pulp_file because in my case it was also out of date which caused me more time. pulp_file on the other hand is always up to date and we don't have to build additional things to help ensure that is true. We should really think hard if all this effort is (a) actually creating a better experience and (b) worth the cost it takes to maintain it.
I really think we should reconsider plugin_template entirely and delete it.
#6 Updated by bizhang over 3 years ago
I'm not convinced that pulp_file should serve as the de facto getting started guide.
The way I see it the plugin_template defines the minimum expectations for a generic plugin. pulp_file is simple and great but has things outside of this minimum set such as:
These are things necessary for the file_plugin to function, but are not needed for other plugins. My expectation for a bootstrapping template is that it should include only additive things, and not subtractive; I should not have to understand the pulp_file specific decisions in order to get started.
I think the best experience is an up to date plugin_template. I share the concerns over the complexity of keeping documentation in two different places and how to keep those documentation up to date. But I think in this case, my concerns are addressed with the promised plugin_template tests; if a change to the plugin API breaks the template, the person initiating that change has to make a PR to the plugin_template, and update the documentation along with that change. I think this process will keep our plugin writer's guide more up to date than the current way.
#7 Updated by firstname.lastname@example.org over 3 years ago
bmbouter, I want to point out that you don't have to do the renaming. `bootstrap.py` handles all of the grunt work, and new plugin writers start with a functional plugin. This is a huge advantage for new plugin writers, they only have to add things to something that already works. I had a very nice experience using the template to bootstrap docker 4.0. Everything just worked, and was very little effort.
It is difficult for new contributors to know the difference between what is required of all plugins and what the file plugin does. The exercise of stripping down the plugin would require knowledge of the file plugin, and I think it would waste a lot of plugin writer time.
Additionally, the comments in the file plugin are intended for file plugin developers, not plugin writers, and may not be very helpful. Plugin writers should be taught based on a simple example with comments that are intended for new plugin writers. The file plugin will still be an excellent resource, but isn't great for getting started.
I disagree that removing the plugin writer from pulpcore is a problem. None of the information is necessary for users, and will not likely be used by plugin maintainers either. Since it is a distinct use case, IMO there is no problem with separating it. In cases where the Plugin API changes and the template needs to be updated, we will already need PRs across repositories, so we aren't adding a new burden. And, as Bihan mentioned, in those cases the tests will fail. If we do want to host them, rtd is very easy and low maintenance.
I think this will not be a heavy maintenance burden, and will significantly lower the barrier to entry for plugin writers.
#9 Updated by bmbouter over 3 years ago
These comments have convinced me that we should keep the plugin_template because:
- bootstrap.py presents distinct value than pulp_file
- the extra pulp_file specific things are not helping plugin writers for other content types
I'm +1 to groom then also because it probably will improve the plugin_template greatly and deleting plugin_template isn't an option.
Thank you for writing all of this out.