https://blog.readthedocs.comRead the Docs Blog - Posts tagged documentation2024-01-10T23:05:10.887894+00:00ABloghttps://blog.readthedocs.com/announcing-pydoc-io/Announcing pydoc.io beta2016-11-17T00:00:00+00:00Eric Holscher<section id="announcing-pydoc-io-beta">
<p>Today we’re excited to announce our latest project: <a class="reference external" href="https://pydoc.io">https://pydoc.io</a>.
This work was made possible by the <a class="reference internal" href="../../../rtd-awarded-mozilla-open-source-support-grant/"><span class="doc">MOSS Grant</span></a> from Mozilla.
Thanks to Mozilla for funding our time building this wonderful community resource.</p>
<section id="about-pydoc-io">
<h2>About pydoc.io</h2>
<p>Running Read the Docs,
we’ve always been proud of the documentation tooling that the Python community has.
We prioritize prose over API documentation listings,
and generally have a high standard of documentation in our projects.</p>
<p>There are a specific set of use cases that API reference documentation support,
and the Python community doesn’t support them well.
Tools like <a class="reference external" href="http://godoc.org">http://godoc.org</a> and <a class="reference external" href="http://rubydoc.info">http://rubydoc.info</a> provide these for others languages,
and we now introduce <a class="reference external" href="http://pydoc.io">http://pydoc.io</a> as the Python community’s version of that.</p>
</section>
<section id="what-is-it">
<h2>What is it?</h2>
<p>Pydoc.io will eventually auto-generate API reference documentation for every package on PyPI.
Our beta release will support a limited set of packages that we are using for testing.
Over time we’ll expand the tooling to automatically support generating docs for any package posted on PyPI.</p>
<p>Reference documentation is wonderful for folks who already know how a library works,
and simply want to use it.
It’s also great for navigating and understanding the internals of a piece of code.
Giving them simple access to nicely rendered API documentation supports using and understanding libraries in a nicer way than reading code.
We’re happy to build out these tools,
along with the wonderful prose tools we’ve always had with Sphinx itself.</p>
<p>Our progress and some context is tracked in <a class="reference external" href="https://github.com/rtfd/readthedocs.org/issues/1957">issue 1957</a>.</p>
</section>
<section id="the-tools">
<h2>The tools</h2>
<p>This project is built on top of <a class="reference external" href="https://github.com/sphinx-doc/sphinx">Sphinx</a> at it’s core.
On top of that,
we’ve layered a few different tools:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/rtfd/sphinx-autoapi/">sphinx-autoapi</a> which is the tool that takes Python source files and turns them into rST.</p>
<ul>
<li><p>Internally, this uses the <a class="reference external" href="https://github.com/PyCQA/pydocstyle/">pydocstyle</a> AST parser, which we use for a parse-only representation of the Python files.</p></li>
</ul>
</li>
<li><p><a class="reference external" href="https://github.com/rtfd/pydoc.io">pydoc.io</a> is a Django application that is the actual web front-end and documentation building code.</p></li>
<li><p><a class="reference external" href="https://github.com/rtfd/apitheme/">sphinx-apitheme</a> is the Sphinx theme that powers the actual API listing pages.</p></li>
</ul>
<p>The biggest piece to call out here is the parse-only documentation generation.
Sphinx’s autodoc module,
and most Python documentation generators rely on importing the code to get docstrings.
As we’ve learned with Read the Docs,
this is quite impractical for a large set of libraries,
including the scientific ecosystem that heavily relies on C libraries.
<strong>Building and supporting a parse-only API tool makes doc builds faster and more reliable.</strong></p>
<p>We have built on top of the <code class="docutils literal notranslate"><span class="pre">pydocstyle</span></code> AST,
but it looks like we’ll likely have to build out our own AST traversal to retrieve all docstrings and construct declarations that we need to output.
We have looked into some of the <a class="reference external" href="https://github.com/davidhalter/jedi/issues/630">other AST options</a> in Python,
but haven’t decided on what direction we want to go when building our own.</p>
<p>We have put a good deal of work into all these different pieces,
but there is still a lot of work to be done.</p>
</section>
<section id="give-us-feedback">
<h2>Give us feedback</h2>
<p><strong>This is a very beta release</strong>.
We have developed a few different sets of tools,
and would love your feedback.
In particular:</p>
<ul class="simple">
<li><p>Give us examples of API documentation patterns that you like. We’d like to incorporate powerful patterns into our theme.</p></li>
<li><p>Don’t give us feedback on specific design issues with the theme, we’re still working on it!</p></li>
<li><p>Let us know if you have ideas about how we can improve the general usability of the documentation</p></li>
<li><p>Let us know features that you wish the site had</p></li>
</ul>
</section>
<section id="thanks">
<h2>Thanks</h2>
<p>Thanks again to Mozilla,
who funded this work.
It wouldn’t have been possible without them,
and we’re happy they funded the initial development.
We’re always looking at ways to make the ongoing maintenance sustainable,
so please reach out to us if you’d like to help with our efforts!</p>
</section>
</section>
Today we’re excited to announce our latest project: https://pydoc.io.
This work was made possible by the MOSS Grant from Mozilla.
Thanks to Mozilla for funding our time building this wonderful community resource.Running Read the Docs,
we’ve always been proud of the documentation tooling that the Python community has.
We prioritize prose over API documentation listings,
and generally have a high standard of documentation in our projects.2016-11-17T00:00:00+00:00