move Sphinx into requirements.txt, adjust info about building documentation
ClosedPublic

Authored by garretraziel on Jun 10 2014, 8:50 AM.

Details

Summary

Sphinx is unable to use virtualenv, so it should be installed
from PyPI (not repos). Also, change info in development guide about
building documentation.

Test Plan

Created new virtual environment, pip -r requirements.txt,
tried to build documentation via make html.

Diff Detail

Repository
rLTRN libtaskotron
Lint
Lint Skipped
Unit
Unit Tests Skipped
garretraziel retitled this revision from to move Sphinx into requirements.txt, adjust info about building documentation.Jun 10 2014, 8:50 AM
garretraziel updated this object.
garretraziel edited the test plan for this revision. (Show Details)
garretraziel added reviewers: kparal, jskladan.
kparal added inline comments.Jun 10 2014, 10:29 AM
docs/source/devguide.rst
261–265

Can you please say something like:

Because system-installed Sphinx is not able to import libraries from virtualenv (bug 1454), it needs to be installed in virtualenv as well::

It seems to be a clearer explanation to me.

requirements.txt
13

Now that I think of it, I'm not sure if we want to have Sphinx installed by default, or if we want people to read through the devguide and install it only when they need it. It's not a dependency of libtaskotron.

It's true that the spec file was not adjusted, and requirements.txt is mainly for developers (it also contains pytest, which is not a dependency of libtaskotron either), so it makes sense, but still I'd like to hear someone else's opinion as well. @tflink, what do you think?

  • change doc about building documentation

Another problem is, when user wants to build documentation, he should read about installing Sphinx and building documentation in devguide and he obviously can't do that (because he hadn't built it yet). I think that there should be line or two about building documentation in readme.rst.

There used to be a short section, but then it got moved to the dev guide to reduce the duplication, I guess. We didn't realize that you can see documentation without instructions how to build it :-) Unless you don't want to read the source code, that is.

I'd be in favor of returning a short excerpt of documentation building into README. Either it should contain information how to install Sphinx and then it doesn't have to be in requirements.txt, or vice versa. Maybe the latter approach is just generally simpler.

  • add info about documentation into readme.rst
kparal accepted this revision.Jun 12 2014, 3:24 PM

If no one else objects in time, please push :)

readme.rst
135

I know you wanted to link the section originally, but since we don't "build" readme, it didn't make sense. Still, it's a bit confusing. Maybe something like this?

The documentation is easy to build if you have followed the instructions to set up a development environment.

This revision is now accepted and ready to land.Jun 12 2014, 3:24 PM
garretraziel closed this revision.Jun 16 2014, 9:01 AM
garretraziel updated this revision to Diff 414.

Closed by commit rLTRN3e116e6e7d42 (authored by Garret Raziel <boloomka@gmail.com>).