[Pulp-dev] Markdown docs - pulpcore and plugins

Mon May 4 16:17:06 UTC 2020

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.aguiar at 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 <bmbouter at 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.aguiar at 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 <daviddavis at 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 <pamp at 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-bounces at redhat.com <pulp-dev-bounces at redhat.com> on
>>>>> behalf of Brian Bouterse <bmbouter at redhat.com>
>>>>> *Sent:* 01 May 2020 20:59:18
>>>>> *To:* Fabricio Aguiar <fabricio.aguiar at redhat.com>
>>>>> *Cc:* Pulp-dev <pulp-dev at 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.aguiar at 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 at redhat.com
>>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>>
>>>>> _______________________________________________
>>>>> Pulp-dev mailing list
>>>>> Pulp-dev at redhat.com
>>>>> https://www.redhat.com/mailman/listinfo/pulp-dev
>>>>>
>>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20200504/72d04716/attachment.htm>