<div dir="ltr">Brian, I liked this idea, but I think pypi will only get the README part of the docs, not sure if it is enough<br clear="all"><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div dir="ltr"><br>Best regards,</div><div dir="ltr"><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize">Fabricio</span><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize"> </span><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize">Aguiar</span><div>Software Engineer, Pulp Project</div><div><a href="https://www.redhat.com/" style="color:rgb(0,136,206);font-family:RedHatText,sans-serif;font-size:12px;margin:0px" target="_blank">Red Hat Brazil - Latam</a><br></div><div>+55 11 999652368</div><div><img src="https://marketing-outfit-prod-images.s3-us-west-2.amazonaws.com/f5445ae0c9ddafd5b2f1836854d7416a/Logo-RedHat-Email.png" width="96" height="22"></div></div></div></div></div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, May 4, 2020 at 11:53 AM Brian Bouterse <<a href="mailto:bmbouter@redhat.com">bmbouter@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>I misunderstood the PR <a href="https://github.com/pulp/pulp_file/pull/386" target="_blank">https://github.com/pulp/pulp_file/pull/386</a>. 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.</div><div><br></div><div>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.</div><div><br></div><div>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. <a href="https://pypi.org/project/pulp-file-client/" target="_blank">https://pypi.org/project/pulp-file-client/</a> ? 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?</div><div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, May 4, 2020 at 10:21 AM Fabricio Aguiar <<a href="mailto:fabricio.aguiar@redhat.com" target="_blank">fabricio.aguiar@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">Clarifying the email, <div>My original thought was: </div><div>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,</div><div>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<br clear="all"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><br>Best regards,</div><div dir="ltr"><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize">Fabricio</span><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize"> </span><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize">Aguiar</span><div>Software Engineer, Pulp Project</div><div><a href="https://www.redhat.com/" style="color:rgb(0,136,206);font-family:RedHatText,sans-serif;font-size:12px;margin:0px" target="_blank">Red Hat Brazil - Latam</a><br></div><div>+55 11 999652368</div><div><img src="https://marketing-outfit-prod-images.s3-us-west-2.amazonaws.com/f5445ae0c9ddafd5b2f1836854d7416a/Logo-RedHat-Email.png" width="96" height="22"></div></div></div></div></div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, May 4, 2020 at 9:10 AM David Davis <<a href="mailto:daviddavis@redhat.com" target="_blank">daviddavis@redhat.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">+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.<div><br></div><div>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?<br clear="all"><div><div dir="ltr"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><br></div><div>David</div></div></div></div></div></div></div></div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, May 4, 2020 at 7:48 AM Quirin Pamp <<a href="mailto:pamp@atix.de" target="_blank">pamp@atix.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">




<div dir="ltr">
<div id="gmail-m_-8526524139181042771gmail-m_6058869894355004407gmail-m_-4565877965497267517gmail-m_122484362205136850gmail-m_6690522927496900062divtagdefaultwrapper" style="font-size:12pt;color:rgb(0,0,0);font-family:Calibri,Helvetica,sans-serif" dir="ltr">
<p style="margin-top:0px;margin-bottom:0px">Am I understanding this correctly, that you (ultimately) want to convert all existing reStructuredText documentation to markdown instead?</p>
<p style="margin-top:0px;margin-bottom:0px"><br>
</p>
<p style="margin-top:0px;margin-bottom:0px">If so, will you also be updating the plugin template?</p>
<p style="margin-top:0px;margin-bottom:0px">Or is pulp_file the reference implementation to watch here?</p>
<p style="margin-top:0px;margin-bottom:0px"><br>
</p>
<p style="margin-top:0px;margin-bottom:0px">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. ;-)</p>
<p style="margin-top:0px;margin-bottom:0px"><br>
</p>
<p style="margin-top:0px;margin-bottom:0px">regards,</p>
<p style="margin-top:0px;margin-bottom:0px">Quirin Pamp</p>
<p style="margin-top:0px;margin-bottom:0px"><br>
</p>
<p style="margin-top:0px;margin-bottom:0px"><br>
</p>
</div>
<hr style="display:inline-block;width:98%">
<div id="gmail-m_-8526524139181042771gmail-m_6058869894355004407gmail-m_-4565877965497267517gmail-m_122484362205136850gmail-m_6690522927496900062divRplyFwdMsg" dir="ltr"><font style="font-size:11pt" face="Calibri, sans-serif" color="#000000"><b>From:</b> <a href="mailto:pulp-dev-bounces@redhat.com" target="_blank">pulp-dev-bounces@redhat.com</a> <<a href="mailto:pulp-dev-bounces@redhat.com" target="_blank">pulp-dev-bounces@redhat.com</a>> on behalf of Brian Bouterse <<a href="mailto:bmbouter@redhat.com" target="_blank">bmbouter@redhat.com</a>><br>
<b>Sent:</b> 01 May 2020 20:59:18<br>
<b>To:</b> Fabricio Aguiar <<a href="mailto:fabricio.aguiar@redhat.com" target="_blank">fabricio.aguiar@redhat.com</a>><br>
<b>Cc:</b> Pulp-dev <<a href="mailto:pulp-dev@redhat.com" target="_blank">pulp-dev@redhat.com</a>><br>
<b>Subject:</b> Re: [Pulp-dev] Markdown docs - pulpcore and plugins</font>
<div> </div>
</div>
<div>
<div dir="ltr">
<div>+1 to pulpcore and pulp_file switching to markdown. It's quicker to write and easier to read.</div>
<div><br>
</div>
<div>Once a few days have passed for any concerns to be raised, if none are, then how about this for a plan?</div>
<div><br>
</div>
<div>1) merge your PR for pulp_file</div>
<div>2) verify that the docs show up on <a href="https://pulp-file.readthedocs.io/" target="_blank">
https://pulp-file.readthedocs.io/</a> correctly</div>
<div>3) start into a PR to convert pulpcore documentation to markdown<br>
</div>
<div><br>
</div>
</div>
<br>
<div>
<div dir="ltr">On Thu, Apr 30, 2020 at 3:01 PM Fabricio Aguiar <<a href="mailto:fabricio.aguiar@redhat.com" target="_blank">fabricio.aguiar@redhat.com</a>> wrote:<br>
</div>
<blockquote style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div dir="ltr">Due issue <a href="https://pulp.plan.io/issues/6518" target="_blank">
6518</a>, about documenting the python clients,
<div>I searched about how to use markdown on sphinx and found this [1]</div>
<div>This helped me to document pulp_file client [2], currently, it introduces markdown docs from the client, keeping the pulp_file rst docs.</div>
<div><br>
</div>
<div>Instead of getting mixed formats for docs, </div>
<div>I propose we move our current docs to markdown, </div>
<div>please share your thoughts! </div>
<div><br>
</div>
<div>[1] <a href="https://www.sphinx-doc.org/en/master/usage/markdown.html" target="_blank">https://www.sphinx-doc.org/en/master/usage/markdown.html</a></div>
<div>[2] <a href="https://github.com/pulp/pulp_file/pull/386" target="_blank">https://github.com/pulp/pulp_file/pull/386</a><br clear="all">
<div>
<div dir="ltr">
<div dir="ltr">
<div dir="ltr"><br>
Best regards,</div>
<div dir="ltr"><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize">Fabricio</span><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize"> </span><span style="color:rgb(0,0,0);font-family:RedHatText,sans-serif;font-size:14px;font-weight:700;text-transform:capitalize">Aguiar</span>
<div>Software Engineer, Pulp Project</div>
<div><a href="https://www.redhat.com/" style="color:rgb(0,136,206);font-family:RedHatText,sans-serif;font-size:12px;margin:0px" target="_blank">Red Hat Brazil - Latam</a><br>
</div>
<div>+55 11 999652368</div>
<div><img src="https://marketing-outfit-prod-images.s3-us-west-2.amazonaws.com/f5445ae0c9ddafd5b2f1836854d7416a/Logo-RedHat-Email.png" width="96" height="22"></div>
</div>
</div>
</div>
</div>
</div>
</div>
_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote>
</div>
</div>
</div>

_______________________________________________<br>
Pulp-dev mailing list<br>
<a href="mailto:Pulp-dev@redhat.com" target="_blank">Pulp-dev@redhat.com</a><br>
<a href="https://www.redhat.com/mailman/listinfo/pulp-dev" rel="noreferrer" target="_blank">https://www.redhat.com/mailman/listinfo/pulp-dev</a><br>
</blockquote></div>
</blockquote></div>
</blockquote></div></div>
</blockquote></div>