[Pulp-dev] Markdown docs - pulpcore and plugins

[Fabricio Aguiar]

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/1fdda500/attachment.htm>