Sphinx alternatives for documentation

[jeongyoonlee]

This post discusses CausalML's documentation tool of choice and potential alternatives with pros and cons.

CausalML uses Sphinx for documentation, which uses the reStructuredText (RST) format.

On the other hand, we maintain other documents written in the Markdown format in the repository, some of which duplicate the Sphinx docs. e.g., README.md and Release notes.

Should we consider a documentation tool that supports Markdown instead of Sphinx? Please feel free to leave your thoughts.

[ras44]

Would it be valid to say that it is more cumbersome to update the RST files and then re-render causalml.readthedocs.io than it is to edit a markdown file? For example, to add images to a GitHub markdown doc, we can just paste in a screenshot to the GitHub editor and the image is stored outside of the repo, but I believe with RST you have to include the image in the repo and then reference it.

Some additional questions:

• Curious if we would lose any features by moving away from Sphinx?

• Unsure what markdown options exist and how it would be structured?

  • Would it be possible to avoid static site generation entirely and keep everything within markdown/jupyter notebooks?

• In either case, markdown or Sphinx:

  • I agree that duplicated documentation is a complicating issue- a single source of truth would be more streamlined
  • It might be easier to maintain if we limit the number of screenshots and code snippets (as these outputs and APIs can change) and instead reference the Jupyter examples directly.