[Pulp-dev] Markdown docs - pulpcore and plugins

[David Davis]

+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/ae002fe9/attachment.htm>