Task #3772
Updated by amacdona@redhat.com over 6 years ago
The plugin template will house the bulk of the plugin writer docs. h3. 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. h3. 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 merged into the "planning guide" and should be cut back. Most of this duplicates Pulpcore's docs/overview/concepts.rst. Provide a link to pulpcore's docs/overview/concepts.rst. For that, and explain concepts that are 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 necessary for implementing sync and publish. users. PublishedArtifact, RemoteArtifact, for example. * 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. h3. Code modules: 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.
.