What about documentation?
John Graves
searchable documentation, but I'm not clear on how it gets distributed
with a package or whether it needs to be hosted at some other site.
If there is a docs subdirectory with an index.htm file, presumably
people will be as interested in opening it in their browser as they
are in opening README.txt in their editor. (?)
But then I have this new idea of VIDEO documentation (see, as a first
attempt, a rather too long video http://bit.ly/a1WLAV ). Surely people
would not like to have to download a huge video file as part of a
distribution, but it is easy enough to post the videos and link to
them from the docs. So, if the idea is to link to docs (whether video
or html), perhaps the best place to do that is in the code comments:
def myFunction():
"""
Usual documentation string
http://linkToFullDocumentationIncludingEmbeddedVideo
"""
Thoughts? Suggestions?
will kahn-greene
> Sphinx provides a means of automating the production of indexed,
> searchable documentation, but I'm not clear on how it gets distributed
> with a package or whether it needs to be hosted at some other site.
On the projects I work on, we have the .rst files in the docs/ dir and
those get distributed with the software. Then I use Sphinx to compile
them into HTML and PDF forms and those go on the web-site.
> But then I have this new idea of VIDEO documentation (see, as a first
> attempt, a rather too long video http://bit.ly/a1WLAV ). Surely people
> would not like to have to download a huge video file as part of a
> distribution, but it is easy enough to post the videos and link to
> them from the docs. So, if the idea is to link to docs (whether video
> or html), perhaps the best place to do that is in the code comments:
>
> def myFunction():
> """
> Usual documentation string
> http://linkToFullDocumentationIncludingEmbeddedVideo
> """
> Thoughts? Suggestions?
It's better to ship documentation with the software. That way if the
web-site/hosting goes down, the docs aren't lost and the user can
continue to use the software.
I don't think documentation solely through video is a good idea for a
variety of reasons mostly involving accessibility and maintenance. In
order to search the video, you have to write out the transcript and link
that to the video on the web-site. Otherwise you're denying an
important way of finding and accessing the documentation. If you ever
change my_function, you have to watch the video to make sure it's still
accurate and if it's not, you have to redo it--that's a ton of
maintenance work. To answer your question, I'd rather have text-based
documentation than video documentation if that's the only docs you're
providing.
I do think it's a good idea to put together screencasts and tutorials of
how to use your software in addition to the text-based docs. <shameless
plug>If they're Python-related, submit them to
http://python.mirocommunity.org/ .</shameless plug>
/will
John Gabriele
> Sphinx provides a means of automating the production of indexed,
> searchable documentation, but I'm not clear on how it gets distributed
> with a package or whether it needs to be hosted at some other site.
>
There seems to be something in place for this.
There are docs available for some Cheeseshop packages at <http://
packages.python.org/> (for example: <http://packages.python.org/
distribute/>). However, it looks like you need to *manually* put your
docs there if you want them made available.
IMO, it should be automatic: when you upload a new release of your
project to the Cheeseshop, some process should automatically do
whatever it needs to do in order to convert the things in your
project's `docs` directory into a bunch of static html files and then
upload them be uploaded directly to the corresponding
packages.python.org/your-package location.
When I view a Perl package at search.cpan.org, I can look at the docs
for *any* of its modules. It's all right there. This is a *huge*
advantage over the Cheeseshop, and IMO one of the reasons that the
CPAN is so useful.
---John
Tarek Ziadé
Distribute has a "build_doc" and a "upload_doc" commands that make
these steps semi-automated, FWIW
We could make them subcommands of upload, so the documentation is
transparently sent to package.python.org when you upload your project
at PyPI..
--
Tarek Ziadé | http://ziade.org
Jannis Leidel
+1 :D
Jannis
PS: the standalone version of the "upload_docs" command: http://pypi.python.org/pypi/Sphinx-PyPI-upload
Tarek Ziadé
Sounds like a great feature to add in distutils2 too...
Jannis, are you interested in hacking the upload command in distutils2 ?
We could backport the result in Distribute afterwards
Tarek
John Gabriele
> On Wed, Mar 3, 2010 at 4:34 PM, John Gabriele <jmg3...@gmail.com> wrote:
> > On Feb 19, 5:42 am, John Graves <jg07...@gmail.com> wrote:
>
>
> Distribute has a "build_doc" and a "upload_doc" commands that make
> these steps semi-automated, FWIW
Could you please point me to where I can learn more about the
build_doc command?
I see that the upload_docs command is documented in docs/
setuptools.txt. Does it simply zip up my docs dir and upload that as
is? That would probably be good, that way I could handle generating
the html on my end before uploading (I'm not using Sphinx, but can
populate my own docs dir with html files).
Thanks,
---John
Tarek Ziadé
Mmmm I think I dreamt about build_doc.
upload_docs do create the zipfile, by looking at the upload_dir
locatio, then uploads it
So yes, that works for you
>
> Thanks,
> ---John
Jannis Leidel
Yep, gladly :)
> We could backport the result in Distribute afterwards
Sounds like a plan.
Jannis