On Tue, May 14, 2019 at 6:56 PM Joshua Sullivan (Verb Ext.) < [email protected]> wrote:
> 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... > > As far as understand the only limitation for us are the Python-pip rules which are unable to invoke Pip with Python 3 correctly in our situation. My last attempt was showing Python 3 in Python runtime (e.g. print sys.version), but the pip ran by Bazel to fetch the dependencies could only find Sphinx up to 1.8.x and none of the other Python-3-only packages. Of course we would have strongly preferred to use Python 3, but for now we proceeded with the native Bazel way and hoping to get it sorted upstream soon (it may have been already, haven't checked in a month or so). The GitHub repository lists numerous issues with pip [1], unfortunately. Are you using Bazel with Python 3.5 in that project? I feel like Python is not a first class citizen in Bazel, to be honest. > > 1. Your implementation will not support the autodoc functionality? > > Well, actually I'm not sure, but presumably not without extending more of the Bazel rules as we currently have. IIUC, autodoc will try to do Python-level imports to obtain the docstrings, but Bazel runs everything in a strict sandbox. This means that you will have to find the magic to find the correct path to append to sys.path or actually Python-depend on the sources you want to run autodoc on (and they will be 'installed' as other Python dependencies). However, if your current project is already fully 'Bazelified', those deps/usages should be fairly trivial. > > 1. Will be able to generate documention with a simple bazel build > <filename/directoryname>? > > Ultimately, yes, that's how we do it! (Nit: Bazel works with labels/targets, not like plain files like Make.) $ bazel build docs INFO: Invocation ID: f366be17-a6aa-41b8-b8a4-017fe020147a INFO: Analyzed target //docs:docs (64 packages loaded, 3671 targets configured). INFO: Found 1 target... INFO: Deleting stale sandbox base /home/user/.cache/bazel/_bazel_user/9a5697af4b4898056e1adadcd9c31af8/sandbox Target //docs:docs up-to-date: bazel-bin/docs/html INFO: Elapsed time: 8.841s, Critical Path: 4.94s INFO: 2 processes: 2 linux-sandbox. INFO: Build completed successfully, 3 total actions > 1. Will have to modify sphinx's current conf.py file in order for it > to work with your package? > > Depends on how much you are currently accessing from conf.py and custom extensions. If you're running commands or reading environment variables, you're going to need magic glue - Bazel does not pass the anything down, as everything is deterministic and heavily sandboxed. For us it was even challenging getting the git commit hash in the documentation. > > 1. Will this eliminate the need for __init__.py files in every > sub-directory? > > Not sure what you're referring to? That's just Python 3.3+ behaviour as far as I understand [2]? > > 1. 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. > > It's not so portable. We made quite some assumptions to get started quickly as for what we need. In the current shape it's more like you could use it as inspiration on how to do it for your project. Think of limitations like hardcoded paths, opinionated options passed to sphinx-build, not relying on doctree states, etc. Despite all that I believe it's a nice starting point. > 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!! > I'm glad to hear you're interested in it. Are you familiar with Bazel? If not, are you able to pair with a developer who is in the context of your project? I think it will be either very useful to the extent of required, depending on how complicated your project is regarding the documentation. By the way, I totally forgot to link to some resources where we have started to look at in the beginning. Neither of the two projects I found had a well-shaped solution for us and we had to cherry-pick the ideas from several places. * Drake (no clue what it is, just got some inspiration from there): [3] * Envoy, very similar use case as ours, fully Bazel-powered project, docs together with API docs (Protobuf), but they're using plain shell scripts :-( [4] * However, Envoy has a sort-of nice way of producing autodoc-like content from Protobuf definitions [5] which we used and integrated with the rest to combine it *all* in a single 'bazel build docs'. Hope to update soon with the actual sources so you could have a try. :-) HTH [1]: https://github.com/bazelbuild/rules_python/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+pip [2]: https://stackoverflow.com/a/37140173/1254292 [3]: https://github.com/RobotLocomotion/drake/blob/edddf3c5a70064da652bf626174e6140e1fe82ab/doc/BUILD.bazel [4]: https://github.com/envoyproxy/envoy/tree/e5a3e3cbdf022a19df7dc66f9f50673160c4eaaf/docs [5]: https://github.com/envoyproxy/envoy/tree/e1ac475442899388825fffc45553c69a935e55ce/tools/protodoc -- 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%2BaqKY7tU1sS2mXCZ22tUyCEQ6g4WizoAepC8Z9_UobLGKFw%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
