Skip to content

Conversation

rickeylev
Copy link
Collaborator

@rickeylev rickeylev commented Oct 13, 2023

This lays the groundwork for using Sphinx to generate user-facing documentation and
having it published on readthedocs. It integrates with Bazel Stardoc to generate
MyST-flavored Markdown that Sphinx can process.

There are 4 basic pieces that are glued together:

  1. sphinx_docs: This rule invokes Sphinx to generate e.g. html, latex, etc
  2. sphinx_stardoc: This rule invokes Stardoc to generate MyST-flavored Markdown
    that Sphinx can process
  3. sphinx_build_binary: This rule defines the Sphinx executable with any necessary
    dependencies (e.g. Sphinx extensions, like MyST) to process the docs in (1)
  4. readthedocs_install: This rule does the necessary steps to build the docs and
    put them into the location the readthedocs build process expects. This is basically
    just cp -r, but its cleaner to hide it behind a bazel run command than have
    to put various shell in the readthedocs yaml config.
  • Bump Bazel 6 requirement: 6.0.0 -> 6.20. This is necessary to support
    bzlmod and Stardoc.

Work towards #1332, #1484

Copy link
Collaborator

@aignas aignas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really interesting, thanks for sharing this!

@rickeylev rickeylev force-pushed the rtd branch 3 times, most recently from 86e4dcc to 665f882 Compare October 14, 2023 21:16
@rickeylev rickeylev force-pushed the rtd branch 4 times, most recently from af62831 to 6aaf4ac Compare October 16, 2023 05:57
@rickeylev rickeylev changed the title wip: generate docs using sphinx docs: initial doc generation using sphinx Oct 16, 2023
@rickeylev rickeylev marked this pull request as ready for review October 17, 2023 04:43
@rickeylev
Copy link
Collaborator Author

Ok, I've cleaned this up enough to be ready for an initial review. This PR just lays the groundwork -- I'm not writing the complete porting of docs over to RTD in this PR.

What I'm going to do is:

  1. Land this PR
  2. Reconfigure RTD to read from a new branch, "rtd-testing". This is where I'll push commits to the RTD build process and get it working
  3. Land another PR on main with the changes from (2). At this point, RTD will be building and publish main and our tagged versions.
  4. Enable RTD building for PRs
  5. Then we can port our plain stardoc md/html docs over to Sphinx/RTD. This will require various changes to docstrings etc so that things group and render nicely.

@rickeylev rickeylev changed the title docs: initial doc generation using sphinx docs: initial doc generation using Sphinx Oct 17, 2023
Copy link
Collaborator

@aignas aignas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general this looks great! looking forward to better docs. Maybe linking #1332 should be mentioned in the PR description?

@rickeylev rickeylev mentioned this pull request Oct 17, 2023
5 tasks
@rickeylev
Copy link
Collaborator Author

linking #1332 should be mentioned in the PR description?

Done

@rickeylev rickeylev force-pushed the rtd branch 2 times, most recently from 938e8b2 to 6964be2 Compare October 17, 2023 19:50
@rickeylev rickeylev added this pull request to the merge queue Oct 17, 2023
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Oct 17, 2023
@rickeylev rickeylev enabled auto-merge October 17, 2023 20:09
@rickeylev rickeylev added this pull request to the merge queue Oct 17, 2023
Merged via the queue into bazel-contrib:main with commit ede4fd4 Oct 17, 2023
@rickeylev rickeylev deleted the rtd branch October 17, 2023 20:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants