Season of Docs 2021 Report Joannah Nanjekye: Reorganizing the SymPy Documentation - sympy/sympy GitHub Wiki

Introduction

Before this project, SymPy documentation was difficult to navigate for users since the key topics were hidden in a big table of contents. During this project, I did an audit and implemented a reorganization of all the documentation. The rest of this report discusses what transpired in the last five months, and suggestions for future work.

Project Goals

The main aim of the reorganization as I communicated during the application period was to achieve the following goals:

  • Reorganize the documentation following the Diátaxis documentation structure.
  • Migrate a few agreed-upon contents from the wiki pages.
  • Ensure the documentation pages are responsive.

The New Documentation Structure

We used the Diátaxis documentation structure which dictates that the documentation is divided into four main parts; Getting started, How-to guides, Reference, and Explanation.

According to SymPy's needs, Diátaxis's four-category documentation structure works better than other tools we know of like DITA and Redhat's modular documentation system. The structure gives a clear scope and sets a clear tone on where each piece of information should go, for both users and documentation authors. The following is an extract of the categories and a description of their contents.

SymPy Tutorials

Tutorials introduce Sympy features to people who are new to the project. It includes installation instructions, a basic introduction to Sympy operations and common gotchas.

How-to Guides

These are step-by-step intructions on how to do different key developer tasks. It details instructions on installing SymPy from source for development. The development setup and workflow is also discussed with elaborate details on debugging, building the docs, and general guidelines on writing documentation and docstrings.

Explanation

Intermediate SymPy users and developers should reference this category of documentation for common pitfalls and advanced topics. The core SymPy features like variables, functions, symbolic expressions are detailed but it does not completely exhaust all SymPy operations.

SymPy API Reference

This category has a detailed description of the SymPy API, it discusses what the different functions and modules do, their arguments and return values.

Progress

We broke the project down to nine core tasks, including a new task to change the theme for the documentation.

  • Getting Started (#21747)
  • Contributor Guide (#21894)
  • Tutorials (#22002)
  • Explanation (#22001)
  • How-to Guides (#22102)
  • Public API reference (#22009)
  • Internal API reference (#22444) (WIP)
  • Elaborate on the meaning of the categories (#22504)
  • Change the theme

The internal API reference is a new subproject to document the private API. It was agreed to be merged as is but it is still work-in-progress, see the subproject README page for more details. I did not get to work on changing the theme, the task is discussed under future work next.

Future Work

A New Sphinx Theme

I suggested changing the documentation theme from classic. I propose the Furo theme used by CPython, NumPy, and Pandas, etc. In my view, this would give us a better layout for seamless navigation of the documentation.

Linking the Internal Reference Subproject

  • The internal reference subproject needs a way to link to the main docs project.
  • It is better to use intersphinx though using an index page is easier and fine too. The later may require moving the subproject to /src/ instead from experience.

Relevant Links

Audit Report

  1. Reorganizing the SymPy Documentation

Issues

  1. Reorganizing the SymPy Documentation
  2. Categorize SymPy Modules
  3. Use autoapi for the internal reference documentation

Pull Requests

  1. Docs: Getting started category
  2. Docs: Add Contributor Guide
  3. Docs: Add Explanation Category
  4. Docs: Add Tutorials Category
  5. Docs: Add How-to Guide Category
  6. Docs: Elaborate the main categories
  7. Docs: Sympy Internal Reference
  8. Docs: Add public API reference section

Conclusion

We achieved all of the planned activities as described in the GSoD proposal. All the existing documentation is reorganized. We decided to add new documentation for the Internal API reference, and considered changing the theme, of which were sort of new things. These can be finished in the future.

I will focus on merging the remaining open pull requests but also hang around for a week for any feedback from the community on the work I have done. Thanks to Aaron and Oscar for the guidance.