Скачать или смотреть Document Your Scientific Project With Markdown, Sphinx, and Read the Docs | PyData Global 2021

Document Your Scientific Project With Markdown, Sphinx, and Read the Docs
Speakers: Juan Luis Cano Rodríguez

Summary
Let's be honest: we like the projects we use to be well-documented, but we almost never have time to document ours. How can we make writing documentation for our Data Science project be as pleasant as possible?

In this workshop you will document a Data Science project using Sphinx, leveraging Markdown and Jupyter notebooks, and we will deploy the result to Read the Docs.

Description
The talk will loosely follow the structure of the official Sphinx tutorial, using Markdown instead of reStructuredText to be more approachable for contributors:

-1. Creating your Sphinx project (15 minutes)

Tutorial introduction, basic project scaffolding using sphinx-quickstart, explanation of the different files that were created.

-2. MyST vs reStructuredText (5 minutes)

Differences between the two markup languages, current status of the ecosystem, pros and cons.

-3. Write Markdown, build HTML (15 minutes)

First steps writing prose documentation using MyST, a flavor of Markdown compatible with Sphinx that adds roles and directives from reStructuredText. Building of HTML documentation using the Sphinx Makefile.

-4. Customizing Sphinx (10 minutes)

Enabling extensions: sphinx.ext.durations to measure performance, furo to use different HTML themes.

-5. Adding cross references (10 minutes)

Adding cross references to other pages of the documentation, specific targets, and objects outside our own project using intersphinx.

-6. Integrating Jupyter notebooks (10 minutes)

Using Jupyter notebooks as pages for the Sphinx documentation, tips and tricks for interactive widgets.

-7. Documenting code automatically (15 minutes)

Leveraging Sphinx code documentation capabilities. Using autodoc to integrate docs from Python docstrings.

-8. Deploying to Read the Docs (10 minutes)

Creating a project on Read the Docs for automatic deployment of the documentation. Enabling pull request reviews.

Juan Luis Cano Rodríguez's Bio
Juan Luis Cano is an Aerospace Engineer with a passion for scientific computing, applied math, programming, education, and outreach. He works as Developer Advocate at Read the Docs, where he works with scientific projects to improve their documentation. He has worked as a software engineer in the space, consulting, and banking industries, and as a Python trainer for several private and public entities.

Apart from being a long-time user and contributor to many projects in the scientific Python stack (NumPy, SciPy, Astropy) he has published several open-source packages, the most important one being poliastro, an open-source Python library for Orbital Mechanics used in academia and industry.

Finally, Juan Luis is the founder and former chair of the Python España association, the point of contact for the Spanish Python community, and former organizer of PyCon Spain, which attracted more than 800 attendees in its last in-person edition in 2019.

GitHub: https://github.com/astrojuanlu/
Twitter:   / juanluisback  
LinkedIn:   / juanluiscanor  

PyData Global 2021
Website: https://pydata.org/global2021/
LinkedIn:   / pydata-global  
Twitter:   / pydata  

www.pydata.org

PyData is an educational program of NumFOCUS, a 501(c)3 non-profit organization in the United States. PyData provides a forum for the international community of users and developers of data analysis tools to share ideas and learn from each other. The global PyData network promotes discussion of best practices, new approaches, and emerging technologies for data management, processing, analytics, and visualization. PyData communities approach data science using many languages, including (but not limited to) Python, Julia, and R.

PyData conferences aim to be accessible and community-driven, with novice to advanced level presentations. PyData tutorials and talks bring attendees the latest project features along with cutting-edge use cases.

00:00 Welcome!
00:10 Help us add time stamps or captions to this video! See the description for details.

Want to help add timestamps to our YouTube videos to help with discoverability? Find out more here: https://github.com/numfocus/YouTubeVi...