[Pulp-dev] Markdown docs - pulpcore and plugins

[Brian Bouterse]

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/8e935eb4/attachment.htm>