Description:

Objective:

Equip participants with the knowledge and practical skills to automate the creation and maintenance of high-quality project documentation using Sphinx, reStructuredText (reST), ReadTheDocs, MkDocs, and related tools.

Target Audience

Python developers, technical writers, and project maintainers looking to streamline and enhance their documentation processes.

Outline:

Embarking on a Documentation Adventure

We’ll kick off the workshop by diving into the significance of having comprehensive, up-to-date, and versioned documentation.

Discover several different types of technical documents and how automation can transform your documentation process.

We’ll also provide an exciting overview of the various tools and workflows we’ll explore, setting the stage for the learning journey ahead.

Sphinx Essentials

Next up, we’ll focus on setting up Sphinx, and familiarize ourselves with the fundamental commands.

We’ll navigate through its directory structure and identify the key files essential for Sphinx-based documentation,

the various data output formats it supports, and the markup languages it can handle.

Gain a comprehensive understanding of how Sphinx works.

By the end, you’ll have a solid grasp of the common Sphinx commands and the overall workflow, making documentation a breeze!

Exercise 1: Setting Up: Set up a Sphinx project, and build your initial documentation.

Exercise 2: Sphinx Quiz: Test your knowledge of the Sphinx workflow and commands with a fun quiz! Compete with your peers and see who grasped the most about the setup process, key commands, and the Sphinx workflow to reinforce your understanding.

Unleashing reStructuredText (reST)

Welcome to the world of reStructuredText (reST), a powerful and flexible markup language widely used for technical documentation.

In this section, you’ll learn the fundamental syntax and structure of reST, explore essential directives, and engage in practical exercises to reinforce your understanding.

Exercise 3: Crafting Your First reST Document: Create a reST document that matches the provided output file. Practice organizing your document with proper structure, headings, lists, code blocks, and images. This exercise will help you get comfortable with the basics of ReST.

Exercise 4: Building a Multi-File reST Project: Take your skills to the next level by creating a multi-file project. Match the provided output files and practice using directives such as TOC (Table of Contents), index pages, and inter-document links. This exercise will enhance your ability to manage larger documentation projects.

(Optional) Exercise 5: Advanced Directives: Create a reST document that matches the provided output file. Practice creating custom roles and directives, and utilizing advanced directives.

ReadTheDocs (RTD): Your Documentation Ally

Discover the advantages of using ReadTheDocs (RTD) for your documentation projects.

In this section, we’ll discuss the features that make RTD a powerful tool and when it is most beneficial to use it.

You’ll learn how to set up and configure RTD, trigger manual builds, and set up webhooks for automatic builds triggered by repository changes.

Exercise 6: Deploying Your Sphinx Project on ReadTheDocs: Configure your Sphinx project on ReadTheDocs and trigger manual and automated builds. This exercise will guide you through the steps of linking a RTD account to your GitHub repository, and configuring your project for continuous integration.

Requirements: A GitHub account to link with the new ReadTheDocs account that we will create and use.

Sphinx Extensions 101

Get whisked away into the world of the Sphinx ecosystem!

And experience its power through engaging demonstrations of popular extensions.

After a series of demos, you’ll have the chance to choose and integrate any extensions that spark your curiosity, with our guidance.

The range and depth of extensions explored will be tailored to your votes of interest, ensuring a unique and engaging experience.

Here’s a list of some popular extensions we’ll try to demo, grouped in categories:

• Input Formats: Napoleon, MyST-Parser
• Automation: Autodoc, Autosummary, Autosectionlabel
• Integration and Cross-Referencing: Viewcode, Linkcode, InterSphinx, Last Updated by Git
• Hosting and Error Handling: Github Pages, Not Found extension
• Executable Code Examples: Doctest, Prompt, HTTP Domain
• Utilities: IfConfig, Todo
• Quality Assurance: Coverage, Spelling
• Visual Enhancements: Graphviz, ImgMath, Inheritance diagrams
• Branding and Identity: Favicon, Shields

Feel free to recommend any other well-known extensions that you want to experience as part of the workshop, in the comments below.

Exercise 7: Extension Connoisseur: Choose at least 2 extensions and apply them in your project, solidifying your understanding of utilizing Sphinx extensions.

Sphinx Tailoring: Custom Extensions

Learn how to effortlessly create custom Sphinx extensions, harness the power of extension hooks, and seamlessly weave them into your project.

This will enable you to extend the functionality of Sphinx to meet your specific needs.

Exercise 8: Docstat Tracker: Create a custom Sphinx extension that tracks document statistics like word count, the number of sections and images in each page.

Requirements: Basic Python

Sphinx Makeover: Theming Essentials

Dive into the realm of theming options, exploring how to transform the appearance of Sphinx-generated documentation.

We'll discuss their importance in project branding, in ensuring your documentation not only informs but also leaves a lasting impression.

Exercise 9: Tailor your theme: Apply a pre-built theme to your Sphinx documentation and customize it to match increasingly complex targets.

Optional Requirements: HTML, CSS, JS, templates

MkDocs: Gotta catch 'em all!

Having already mastered the art of Sphinx, now it’s time to level up with MkDocs.

We’ll dive into the differences between the mighty reST markup language and the sleek MD, comparing their strengths and quirks. You’ll revisit the robust documentation structures of Sphinx and explore the more streamlined approach of MkDocs. We’ll also take a look at the vibrant plugin ecosystems, contrasting the extensive options available for Sphinx with the versatile plugins of MkDocs. And of course, we’ll discuss the diverse output formats each tool offers.

Exercise 10: MkDocs project Re-do: Take a MkDocs project from setup to deployment.

This exercise will help you apply the concepts you’ve learned with Sphinx to your MkDocs project, giving you a quick refresher on the entire process from setup to RTD integration. By the end, you’ll have internalized the magic of documentation.

Best Practices on Documentation Engineering:

If we stay on track and complete everything on time, we’ll dive into this exciting session where participants can ask their burning questions and get expert advice on the best practices for documentation engineering. It’s your chance to get personalized tips and tricks to make your documentation shine!

• Structuring the documentation code in a maintainable and scalable manner.
• Reuse and recycle: Writing reusable documentation components.
• Following a consistent style guide in documentation code.
• Automate like a boss
• Version control is your friend
• Know your docs: Be familiar with the different types of documentation, like user guides, API docs, technical docs, tutorials, and release notes.

Outcome

By the end of the workshop, you will have:

• Whipped up a sample Sphinx project and deployed it to ReadTheDocs
• Created your own custom Sphinx extension.
• Built a sample MkDocs project and deployed to ReadTheDocs

You’ll be a whiz at:

• Understanding why automated technical documentation is a game-changer.
• Speaking the language of reStructuredText.
• Setting up and configuring Sphinx with ease.
• Getting MkDocs up and running smoothly.
• Integrating your project documentation with ReadTheDocs like a champ.
• Exploring a treasure trove of Sphinx extensions.
• Creating and using custom Sphinx extensions.
• Applying and customizing themes in both Sphinx and MkDocs to make your docs look fabulous.

Prerequisites:

• Familiarity with markup languages like markdown would be essential.
• A GitHub account and the ability to handle basic Git and GitHub operations on your own.
• Familiarity with code documentation, HTML/CSS/JS will give you a leg up.
• Basic knowledge of Python is sufficient.

Speaker Info:

Niloth, from Birla Institute of Technology and Science, Pilani,

is a strong proponent for open source documentation.

He has always been interested in documenting his work for posterity, and has created several documentation projects.

He is currently working with Zulip, an organization that holds documentation as a core principle.

Zulip has well over 150,000 words of documentation, and is still exponentially growing.