hundreds-father-404
05/13/2022, 11:42 PMconf.py
file for settings, and files within a site can easily depend on each other
Proposal:
• Use a target type like sphinx_project()
, whose sources include the conf.py
and all .rst/.md
files in the directory and recursive subdirectories
• To include Python source code, you'd add to the dependencies
field (or we infer)
Alternative:
• File-level modeling, sphinx_source
vs sphinx_sources
Benefits of sphinx_project()
• Less boilerplate
• Easier for us to implement, e.g. no dep inference needed
• Obvious how to support docs from Python source code
Downsides of `sphinx_project()`:
• not good project introspection. You can't use Pants to query which pages depend on which others.
• couldn't say to build a single file rather than whole project (at least w/ current technologysphinx_project()
is the way to go, but curious for feedback before spending more time writing thishigh-yak-85899
05/13/2022, 11:46 PMhundreds-father-404
05/13/2022, 11:48 PMbitter-ability-32190
05/13/2022, 11:54 PMhigh-yak-85899
05/13/2022, 11:57 PM__init__.py
modules throughout if a directory didn't contain any python modules). Other than that, we never needed to do much. It was all handled through conf.py
and associated extensions.hundreds-father-404
05/13/2022, 11:59 PMsphinx_project
target type a lot! For example, we can add a field for what mode(s?) you want to generate in, e.g. HTML. So you change on a per-project basisrhythmic-morning-87313
05/14/2022, 4:07 AMcurved-television-6568
05/14/2022, 5:55 AMhundreds-father-404
05/14/2022, 2:00 PMCan't the sphinx project generate file level targets.Possibly. I think I'm gonna start w/ just
sphinx_project
for now, then we could probably add if there's demandnice-florist-55958
06/15/2022, 8:53 PMpackage
goal on a sphinx_project
expected to be similar to invoking the Makefile that comes with every Sphinx project? Would the output type be specified in the goal's args or the target's params (e.g., "make html", "make pdf")?
Not sure if this would affect the design choice, but we also make heavy use of the IPython Sphinx extensions module that allows your .rst
to drop into an IPython kernel, do some Python, and then save the outputs/plots in a way that a user would experience if they had a console or notebook open. In our build chain we had to make sure that any given project on the repo had a correctly setup virtual env for their docs sub-project to be built correctly and make this type of documentation possible. That turned out to be a bit of a headache, esp. for first-party code (maybe because we have become so accustomed to Pants doing this so elegantly in other situations!); hopeful whatever becomes of this new target, these sorts of things are easily handled :)hundreds-father-404
06/15/2022, 9:03 PMpackage
is like invoking make
to build it
I ended up reverting Sphinx in 2.13 because CI was flaky and the design needs more work. But, it's a foundation and I hope to pick it back up (I want to use Sphinx for Pants itself)nice-florist-55958
06/15/2022, 9:14 PMhundreds-father-404
06/15/2022, 9:18 PMnice-florist-55958
06/17/2022, 9:29 PM