Sphinx is unable to use virtualenv, so it should be installed
from PyPI (not repos). Also, change info in development guide about
building documentation.
Details
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
| docs/source/devguide.rst | ||
|---|---|---|
| 261–265 | Can you please say something like:
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? | |
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.
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?
| |
Can you please say something like:
It seems to be a clearer explanation to me.