Brian, I liked this idea, but I think pypi will only get the README part of the docs, not sure if it is enough
Best regards, Fabricio Aguiar Software Engineer, Pulp Project Red Hat Brazil - Latam <https://www.redhat.com/> +55 11 999652368 On Mon, May 4, 2020 at 11:53 AM Brian Bouterse <bmbou...@redhat.com> wrote: > I misunderstood the PR https://github.com/pulp/pulp_file/pull/386. I > thought it did convert pulp_file entirely to MD using an automated tool, > but I realize now it uses two formats which I'm not as comfortable with. I > am in favor of moving to MD for everything, but if there isn't an automated > tool to do it, then I don't think we should now if it takes that much > effort. > > Let's go back to focusing on the original goal: to document the bindings. > I'm realizing that having auto-generated docs committed in version control > could be an unmanageable process to do manually. Since the docs are > generated I think it needs to be automated; this is similar to how we > handle autodoc with Sphinx today (handled at build time and not in source > tree). I believe we should avoid autogenerated assets from being checked > into the source tree. > > Here's an alternative approach that would avoid checking in the automated > docs to the source tree. What if we publish the docs on the pypi bindings > package pages, e.g. https://pypi.org/project/pulp-file-client/ ? To do > that, the plugin_template would have the bindings build process build the > docs and add them to the asset it publishes to pypi. This also avoids the > docs support of mixed style types issue also. What do others think about > this approach? > > > On Mon, May 4, 2020 at 10:21 AM Fabricio Aguiar < > fabricio.agu...@redhat.com> wrote: > >> Clarifying the email, >> My original thought was: >> if your plugin has a binding client and you want to document it, the way >> I find for doing it is introducing markdown docs from the client, >> as it would end up with 2 docs formats (rST and MD), I wanted the >> hear your thoughts on moving the entire docs to MD, for having only one >> format for it >> >> Best regards, >> Fabricio Aguiar >> Software Engineer, Pulp Project >> Red Hat Brazil - Latam <https://www.redhat.com/> >> +55 11 999652368 >> >> >> On Mon, May 4, 2020 at 9:10 AM David Davis <davidda...@redhat.com> wrote: >> >>> +1 to moving to markdown. I'm imagining that with this move, Markdown >>> will be the lingua franca in Pulp 3 for documentation but it will be >>> ultimately up to plugins to decide what language to use. Moreover, I'm >>> guessing we'll update plugin_template to use Markdown too. >>> >>> I think there are tools that convert rST to Markdown so maybe we could >>> send out an email with instructions for plugins on how to convert their rST >>> docs to Markdown? >>> >>> David >>> >>> >>> On Mon, May 4, 2020 at 7:48 AM Quirin Pamp <p...@atix.de> wrote: >>> >>>> Am I understanding this correctly, that you (ultimately) want to >>>> convert all existing reStructuredText documentation to markdown instead? >>>> >>>> >>>> If so, will you also be updating the plugin template? >>>> >>>> Or is pulp_file the reference implementation to watch here? >>>> >>>> >>>> Currently pulp_deb is overdue for a major rework of its documentation, >>>> but I would like to avoid having to do that twice in a row. ;-) >>>> >>>> >>>> regards, >>>> >>>> Quirin Pamp >>>> >>>> >>>> >>>> ------------------------------ >>>> *From:* pulp-dev-boun...@redhat.com <pulp-dev-boun...@redhat.com> on >>>> behalf of Brian Bouterse <bmbou...@redhat.com> >>>> *Sent:* 01 May 2020 20:59:18 >>>> *To:* Fabricio Aguiar <fabricio.agu...@redhat.com> >>>> *Cc:* Pulp-dev <pulp-dev@redhat.com> >>>> *Subject:* Re: [Pulp-dev] Markdown docs - pulpcore and plugins >>>> >>>> +1 to pulpcore and pulp_file switching to markdown. It's quicker to >>>> write and easier to read. >>>> >>>> Once a few days have passed for any concerns to be raised, if none are, >>>> then how about this for a plan? >>>> >>>> 1) merge your PR for pulp_file >>>> 2) verify that the docs show up on https://pulp-file.readthedocs.io/ >>>> correctly >>>> 3) start into a PR to convert pulpcore documentation to markdown >>>> >>>> >>>> On Thu, Apr 30, 2020 at 3:01 PM Fabricio Aguiar < >>>> fabricio.agu...@redhat.com> wrote: >>>> >>>> Due issue 6518 <https://pulp.plan.io/issues/6518>, about documenting >>>> the python clients, >>>> I searched about how to use markdown on sphinx and found this [1] >>>> This helped me to document pulp_file client [2], currently, it >>>> introduces markdown docs from the client, keeping the pulp_file rst docs. >>>> >>>> Instead of getting mixed formats for docs, >>>> I propose we move our current docs to markdown, >>>> please share your thoughts! >>>> >>>> [1] https://www.sphinx-doc.org/en/master/usage/markdown.html >>>> [2] https://github.com/pulp/pulp_file/pull/386 >>>> >>>> Best regards, >>>> Fabricio Aguiar >>>> Software Engineer, Pulp Project >>>> Red Hat Brazil - Latam <https://www.redhat.com/> >>>> +55 11 999652368 >>>> _______________________________________________ >>>> Pulp-dev mailing list >>>> Pulp-dev@redhat.com >>>> https://www.redhat.com/mailman/listinfo/pulp-dev >>>> >>>> _______________________________________________ >>>> Pulp-dev mailing list >>>> Pulp-dev@redhat.com >>>> https://www.redhat.com/mailman/listinfo/pulp-dev >>>> >>>
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev
