To wrap this up: I'm going to interpret silence as a general lack of interest. Since Rawlin said "I wouldn't have a problem with enabling existing sphinx capabilities," I'm counting that as disinterest in supporting non-extant functionality.
tl;dr: I'll add the deps to requirements.txt but docset support is shelved at least for now. ________________________________________ From: Fieck, Brennan <[email protected]> Sent: Friday, February 22, 2019 3:48 PM To: [email protected] Subject: Re: [EXTERNAL] Re: Docs build system > For 1.2: just to clarify, that's adding the dependencies to the > traffic_control/docs/source/requirements.txt? yeah, exactly > ... I wouldn't have a > problem with enabling existing sphinx capabilities to produce > different output formats when specified, as long as html remains the > default. We're actually already doing this, it's why you can download a PDF from our ReadTheDocs but when you build it yourself it's HTML. However, enabling this would use doc2dash (http://pypi.python.org/pypi/doc2dash) which is *not* "existing sphinx capabilities". I'm not suggesting that we include this dependency in e.g. requirements.txt, but maybe just add the recipe to the existing Makefile. Once that's done we _could_ attempt to contribute it to the Dash/Zeal/Velocity repositories, or just require that people build and import it themselves. ________________________________________ From: Rawlin Peters <[email protected]> Sent: Friday, February 22, 2019 2:13 PM To: [email protected] Subject: [EXTERNAL] Re: Docs build system For 1.2: just to clarify, that's adding the dependencies to the traffic_control/docs/source/requirements.txt? Sounds reasonable to me. For 2: I don't believe I use any of those, but I wouldn't have a problem with enabling existing sphinx capabilities to produce different output formats when specified, as long as html remains the default. - Rawlin On Fri, Feb 22, 2019 at 1:52 PM Fieck, Brennan <[email protected]> wrote: > > I'd like to accomplish two things with this email. > > > 1. See if anybody has a problem adding dependencies to the docs build > > > So first, the docs build system is set up to automatically document the > > Python client (and ORT.py), but relies on importing the package to > > document it. That means that the dependencies of the package need to > > exist or the generated documentation is empty > > (e.g.: > https://traffic-control-cdn.readthedocs.io/en/latest/tools/python_client.html) > > So at this point we have three options as I see it > > 1. Stop auto-documenting > > I hate this idea. Automated documentation is a godsend. Let's not > choose this one. > > 2. Add the dependencies to requirements.txt > > This is currently the most appealing to me. I think if we just add > `distro` > > and `munch` everything will be fine. It does mean maintaining > dependencies in two > > different places. > > 3. Separate dependencies into "base" and "you need these for autodoc" > > This may sound nice at first glance, but the work it takes to get > that to work with > > ReadTheDocs is non-negligible. Probably means adding some custom > scripting to > > conf.py. > > > 2. Gauge interest in a new docs output format > > > Does anybody use Dash/Zeal/Velocity/Xcode when working with the ATC repo? > > We can use the built sphinx documentation to generate docsets that will > integrate > > into those. If it's common enough, I could add it as a build target for > the docs.
