After making some changes to the docs, a user might want to test his or her
fixes by rendering them to html. To render the .rst docs in oh-bugimporters,
there is a Makefile in the docs/ folder and a number of make commands. In order
to make the docs, the python-sphinx package must be installed (I don't think
this is in the virtualenv).
To render the .rst docs in oh-mainline, there is a tools/render_docs.py script
which I have not used. This likely uses some virtualenv magic.
I would suggest we use the oh-mainline convention for oh-bugimporters, because
it appears to be more user-friendly, and there are docs already written for its
use
(http://openhatch.readthedocs.org/en/latest/getting_started/documentation.html),
whereas there aren't any docs for creating documentation in oh-bugimporters.
[...so meta]
tools/render_docs.py relies on oh-mainline's thrilling and terrifying and
shocking strategy of embedding a copy of all its dependencies.
I tried to keep oh-bugimporters a little more "normal", in terms of making
it more like a normal Python project and less like a crazy Asheesh hack
that throws Python community standards to the wind in order to achieve an
epically quick setup process.
For now, I'd suggest simply documenting 'make html', or something else
like 'env/bin/sphinx-build -b html . _build', in the oh-bugimporters docs.
Probably the latter.
FWIW, the world of Python dependencies has gotten a lot better since 2011,
when I flipped out and bundled all of oh-mainline's dependencies. We have
a few options there. My angle is I'd like to see if oh-mainline can become
more Python-community-normal, rather than make oh-bugimporters equally
abnormal.
The other thing I should say is that oh-bugimporters requires lxml, which
is famously hard to install, as it's a C extension and therefore requires
a C compiler. Moving that dependency out of oh-mainline was one of the
motivations for creating oh-bugimporters in the first place. Therefore, it
stands to reason that oh-bugimporters is going to be slightly harder to
set up than oh-mainline. Having said that, none of this should be
construed as me saying that oh-bugimporters should be hard to install
merely to make it hard to install!
I think I'm cool with +1 to just adding a "Documentation" section to
oh-bugimporters, and leaving the two projects separate in that respect. Changed
bug title to reflect this.
I'd definitely prefer documenting the Makefile... it's in source control, it's
there, may as well use it. And typing make html is so much shorter :)
Other than that, only thing that should be mentioned is that python-sphinx is a
dependency. Should/can we add this to the virtualenv instead?
+1 to creating a docs section in oh-bugimporters' docs
+0 to using the Makefile, +0 to documenting it
+1 to adding python-sphinx to the install_requires in the setup.py
that would cause the right things to be around.
Although... ouch, the Makefile isn't set up to use the virtualenv. Hum.
The Makefile would work if you either:
"Activate" the virtualenv, or
Have python-sphinx installed via your system package manager, or
Otherwise have "sphinx" on your path for one reason or another.
Given that, I'm now -0 on documenting the Makefile thing, and I propose at least
emphasizing the env/bin/sphinx flow for generating the docs. If people want to
also/instead use the Makefile, that's fine. No objection to documenting it,
really, merely an objection to emphasizing the Makefile-based strategy.
Comment by ehashman:
To render the .rst docs in oh-mainline, there is a tools/render_docs.py script which I have not used. This likely uses some virtualenv magic.
I would suggest we use the oh-mainline convention for oh-bugimporters, because it appears to be more user-friendly, and there are docs already written for its use (http://openhatch.readthedocs.org/en/latest/getting_started/documentation.html), whereas there aren't any docs for creating documentation in oh-bugimporters. [...so meta]
Comment by paulproteus:
tools/render_docs.py relies on oh-mainline's thrilling and terrifying and shocking strategy of embedding a copy of all its dependencies.
I tried to keep oh-bugimporters a little more "normal", in terms of making it more like a normal Python project and less like a crazy Asheesh hack that throws Python community standards to the wind in order to achieve an epically quick setup process.
For now, I'd suggest simply documenting 'make html', or something else like 'env/bin/sphinx-build -b html . _build', in the oh-bugimporters docs. Probably the latter.
FWIW, the world of Python dependencies has gotten a lot better since 2011, when I flipped out and bundled all of oh-mainline's dependencies. We have a few options there. My angle is I'd like to see if oh-mainline can become more Python-community-normal, rather than make oh-bugimporters equally abnormal.
The other thing I should say is that oh-bugimporters requires lxml, which is famously hard to install, as it's a C extension and therefore requires a C compiler. Moving that dependency out of oh-mainline was one of the motivations for creating oh-bugimporters in the first place. Therefore, it stands to reason that oh-bugimporters is going to be slightly harder to set up than oh-mainline. Having said that, none of this should be construed as me saying that oh-bugimporters should be hard to install merely to make it hard to install!
Comment by ehashman:
I'd definitely prefer documenting the Makefile... it's in source control, it's there, may as well use it. And typing
make htmlis so much shorter :)Other than that, only thing that should be mentioned is that python-sphinx is a dependency. Should/can we add this to the virtualenv instead?
Comment by paulproteus:
+0 to using the Makefile, +0 to documenting it
+1 to adding python-sphinx to the install_requires in the setup.py
that would cause the right things to be around.
Although... ouch, the Makefile isn't set up to use the virtualenv. Hum.
The Makefile would work if you either:
Given that, I'm now -0 on documenting the Makefile thing, and I propose at least emphasizing the env/bin/sphinx flow for generating the docs. If people want to also/instead use the Makefile, that's fine. No objection to documenting it, really, merely an objection to emphasizing the Makefile-based strategy.
Hope this helps.
Status: chatting Nosy List: amagineer, ehashman, paulproteus, younjin Priority: bug Imported from roundup ID: 985 (view archived page) Last modified: 2014-05-13.06:56:53