On Tue, May 14, 2019 at 5:37 PM Joshua Sullivan (Verb Ext.) < [email protected]> wrote:
> Hello all, I am currently working on a project that that specifically is > asking me to not use a Makefile to build all of the dependencies because > there entire repo uses bazel to build files instead. For this reason I > figured the easiest way to do this to start off would be to convert > Sphinx's current MakeFile to command line inputs and just write this into a > short python script. > That's quite a coincidence - soon, we (the company I work for) will release a project to the public that uses Sphinx with Bazel, using Bazel rules (Apache 2 licensed). This means that we currently run 'bazel build docs' and it will correctly build Sphinx documentation without the need for any dependency to install for users (except Python on the host for Bazel Python roles I believe, the rest will be installed by Bazel like it does for other toolchains too). To get back to your question - I think your approach won't help you with Bazel for most use cases of Sphinx. You can invoke a Python script or any other executable instead of a Makefile, but that does not make it Bazel compatible. Basically, Bazel requires everything to be deterministic in and out with specified input/output labels without touching source files. To be able to also feed generated-other-Bazel-rules files to Sphinx's single-input-directory and change options in configuration-by-conf.py was the major pain to overcome. I like Bazel a lot, and I like Sphinx a lot, but it was a bit hard hard to unify their designs. Roughly speaking we have 1) a custom sphinx_main.py that invokes sphinx.cmd.build.main() injecting/snooping some arguments, 2) some glue in conf.py that consumes parameters via Bazel status files and environment variables that we need to pass, 3) output from other applications generating RST input files, 4) rules_sphinx/def.bzl that orchestrates everything. Our solution is currently far from perfect: * Python 2 only, because of Python-pip limitations with Bazel I could not tackle yet. * No incremental builds - if Bazel detects a change on any input, a full Sphinx-rebuild of the docs will be triggered. * No proper autodoc support (yet), because in a Bazel scenario you want Bazel to select the toolchain etc., not Sphinx. We currently build RST files from the sources with other Bazel rules and feed them to Sphinx separately in a temporary input directory. * It's quite monolithic tightly integrated in our project, not something you can import separately yet. * HTML target only for now. I'll post a link in this thread once it's released to the public and I hope it will be helpful to get it kickstarted for you as well. I can't promise anything on the timeline, but I think it will be a matter of days rather than weeks. :-) If there's interest for it, I hope that in the future it could evolve to a separate project in the long list of Bazel rules projects [1], e.g. 'rules_sphinx'. HTH [1]: https://awesomebazel.com/#rules -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/sphinx-users. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAFT%2BaqK%2B6_PfrnzEnPA89H8qf8RbA0%2BMjkn_a3DYeSrmB7Ozbw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
