This sounds exactly like what we are looking for for the most part! I do
have a few clarification questions to ask if you don't mind answering them
just to make sure I'm understanding the capabilities and limitations of
your companies solution in regards to the soon to be released version
correctly.
1. Your implementation will only support Python 2?
1. We just migrated completely over to Python 3.5 last week...
2. Your implementation will not support the autodoc functionality?
3. Will be able to generate documention with a simple bazel build
<filename/directoryname>?
4. Will have to modify sphinx's current conf.py file in order for it to
work with your package?
5. Will this eliminate the need for __init__.py files in every
sub-directory?
6. Lastly, can you explain a little more about what you mean when you
said, "It's quite monolithic tightly integrated in our project, not
something you can import separately yet." and what you were referring to
here.
I appreciate you quick response to my original question! I am very excited
to hear that there will soon be a solution for this, as I have not seen
anything out there quite like what you have described to me and it is
exactly the solution we are looking for by the sounds of it! Please let me
know when this solution is available and I will be very happy to test this
out with our project!!
Thank you again!!
On Tuesday, May 14, 2019 at 11:22:42 AM UTC-5, Gert van Dijk wrote:
>
> On Tue, May 14, 2019 at 5:37 PM Joshua Sullivan (Verb Ext.) <
> [email protected] <javascript:>> 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/a4b7695a-d915-4265-bbb0-bcab54eadb00%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
