I agree pypi will only show the README. I imagined a really long README, but maybe this is not a great approach.
What do other users of openapigenerator use for their Python bindings? Can we ask them to get a recommendation? I'm looking for more ideas because I don't think we can continue with the current solution w/ auto generated docs manually checked into version control. On Mon, May 4, 2020 at 10:58 AM Fabricio Aguiar <fabricio.agu...@redhat.com> wrote: > 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
