[Pulp-dev] Markdown docs - pulpcore and plugins

[Fabricio Aguiar]

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/24cea272/attachment.htm>