External documentation proposal

[Demitri Muna]

Hi,

While working on error messages in coordinates, I found that (of course) I am quite limited in how detailed I can get. It occurred to me that it would be interesting to include a short URL as part of the error message that would take the user to a detailed example and explanation of how they might use the particular feature that's failed. This is not a link to the docs (e.g. API reference), but a tutorial on the specific piece of code. Of course many errors could point to the same tutorial.

I envision something like this:

a = Angle(12.345)

ValueError: units must be specified, http://astropy.org/err?id=5000

That link would then take you to a page that goes into the details of how to specify units. The pages should be short and to the point, i.e. not all lead to a single page per subpackage. They should address exactly the error encountered and then link to further information elsewhere.

I think this would be a great way to hold a user's hand and be able to go into just enough detail to answer users' questions.

As far as implementation, I'd propose that a new directory be made in each subpackage, e.g. "doc" (not "error"!), with a filename of the error code. Further, to save us from having to write a lot of tedious HTML, I'd propose the format be in Markdown. This allows the pages to be easily viewed/edited in GitHub and remain independent of style information - we can implement a new CSS whenever we need.

Part of the unit tests will be to check that each error code has an actual page associated with it.

A server would listen on astropy.org, pull the page based on the error number, render the page from the Markdown, and serve that. I'd suggest (and can help to write) a Flask Python app to do this - that would be pretty trivial. Finally, error codes could be mapped to subpackages, e.g. a "51" prefix means coordinates, "52" units, etc. (Or another other sensible and extensible scheme.)

Thoughts?

Cheers,

Demitri

_________________________________________
Demitri Muna

Center for Cosmology and Particle Physics
New York University

http://scicoder.org/

[Erik Bray]

I like it! I think this is a decent idea. A few things I might do
differently though: I would much prefer to keep any error
documentation closely associated with the code it relates to. I think
it's already hard enough as it is to keep code and user documentation
in sync. And having an entire separate set of documentation that
needs to be referenced and and kept up to date could become
problematic.

So it might be better to somehow keep error-related help directly in
the code it relates to, possibly in module-level or class-level
variables. Static analysis can be used to pull out the relevant error
documentation and associate each one with an ID of some kind. There
should also be some kind of helper function that generates these
exception messages containing URLs in such a way that developers can
reference specific errors without having to give it much thought or
look up the IDs (or even the URL).

Finally, they should be reST, not Markdown, simply for the sake of
consistency with any other documentation we have. If this idea pans
out I'd be happy to help on the server side bits.

Erik B.

[Thomas Robitaille]

This is an excellent proposal - I've always found exceptions very limiting in helping users solve the issue, and this would be a great way to do it.

Just a couple of comments:

- if we want to have a dedicated server (software wise) then I suggest using a sub-domain (help.astropy.org, tutorials.astropy.org, etc.), so that we don't have to interfere with the main pages (astropy.org) that are hosted by github.

- is there a way to render clickable URLs in a terminal? (probably not, but just checking!)

- is there a reason not to include the rst files for these tutorials in the normal documentation for the package? (then the links would just point to docs.astropy.org/...). If the issue is to do with the length of the URL, the actual tutorials could still be in the main docs, and help.astropy.org/err?id=5000 (for example) could just redirect to the appropriate tutorial page on docs.astropy.org.

Cheers,

Tom

[Demitri Muna]

Hi,

On 2 Oct 2012, at 14:16, Erik Bray <erik....@gmail.com> wrote:

I like it! I think this is a decent idea.  A few things I might do
differently though: I would much prefer to keep any error
documentation closely associated with the code it relates to.  I think
it's already hard enough as it is to keep code and user documentation
in sync.  And having an entire separate set of documentation that
needs to be referenced and and kept up to date could become
problematic.

I'm concerned about breaking the flow of the code - large amounts of documentation heavily interspersed with the code will make it impossible to read. I do think they should be kept separate. Keeping it in sync/matched is a little tricky, and I'm still pondering clean ways to do that.

Another reason to keep them separate is that it will be *much* more convenient/easy to write and edit. Editing in-line marked up text is pretty much a non-starter I think.

Finally, they should be reST, not Markdown, simply for the sake of
consistency with any other documentation we have.

Oh all right. :) I found that TextMate can edit and preview reST documents at the same time, so that works for me. The easier it is to create/edit these pages, the more I think they'll be implemented.

On 2 Oct 2012, at 17:14, Thomas Robitaille <thomas.r...@gmail.com> wrote:

- if we want to have a dedicated server (software wise) then I suggest using a sub-domain (help.astropy.org,tutorials.astropy.org, etc.), so that we don't have to interfere with the main pages (astropy.org) that are hosted by github.

In the interest of keeping the URLS as short as possible I actually looked into registering a Paraguay top level domain so we could have "astro.py", but the language and rules got a little complicated. (Anyone here live in Paraguay!?)

With most of us working at large institutions, I'm sure that one will be happy to host such a thing. Heck, I'm sure we could host it here at NYU without a problem. We'll need another host to serve as a mirror for backup. If we chose to go with a subdomain then it could point to a different server of course. These are details we can probably talk about next week more efficiently.

- is there a way to render clickable URLs in a terminal? (probably not, but just checking!)

That will be dependent on the actual Terminal app and OS being used, but no, I doubt it.

- is there a reason not to include the rst files for these tutorials in the normal documentation for the package? (then the links would just point to docs.astropy.org/...). If the issue is to do with the length of the URL, the actual tutorials could still be in the main docs, and help.astropy.org/err?id=5000 (for example) could just redirect to the appropriate tutorial page ondocs.astropy.org.

The idea for the "error" pages is that they address the exact, specific error that the user encountered. This has a huge advantage over the tutorials in that as someone is working, they don't have to get the sense of the tutorial and parse it to see where they went wrong. I see these pages as very short, and should link back to the documentation and tutorials as appropriate, but are designed to zero in on the problem with no other context or extraneous information. An example might be:

---

ValueError: Units must be specified for RA, one of u.degree, u.hour, or u.radian.

When creating an RA [link to RA API] object, a unit must be specified - we don't assume any unit. You did provide a value for the unit, but RA only accepts u.degree, u.hour, or u.radian. These units come from the astropy.unit subpackage, and can be used like this:

import astropy.unit as u

ra = RA(12.34, units=u.hour)

To see other ways units can be specified, see this tutorial [link to more general tutorial].

---

That's all that's needed. This is much better than a general tutorial on how to create Angles or RA objects because it addresses the exact error that the user made and exactly how to fix it. Deep in the code I know what went wrong or what information I'm missing, and this is essentially an opportunity to stand over the user's shoulder and explain things.

Thus, I think these rst pages should be in the subpackage directory (or else some structure that matches the code) since they are very closely tied to the code, not the docs. But you can also see how that's quite a lot of text to be inline with the code I think - it would really get in the way.

Automatically generating/parsing these messages into codes would be nice though. What if the developer created an arbitrary integer error code that only needed to be unique in the scope of the method in question. Then the unique "key" would be "function name + code", e.g. "geometry10", and the parsing code would look for a file called "geometry10.rst" and generate a wholly integer id and URL. Code in other methods could also refer to a method name and id. The parsing code would report whether there are orphan errors or rst files. This is off the top of my head - I don't know how clear this is!

[Michael Droettboom]

The vo package has this problem as well.  It has many warning and exception classes.  The approach taken there is to have a Python module that is basically for exceptions only (voexceptions.py).  Each class has a docstring (which gets built into the docs, of course) as well as the message in a new-style formatting format, so it's easy to just pass in the parts to be filled in to the exceptions constructor.  Since coming up for short names for these exceptions became kind of ridiculous, they each just have a number and the number is manually guaranteed to never change -- if an exception is removed, its place is kept for all eternity, so the numbers at this point are non-contiguous.

The piece that this doesn't have is displaying a URL to a deeper description of the message, which I think is a great idea.  There are parts of vo that generate HTML reports, however, that already do this.  I would definitely be in favor of updating VO to support whatever approach we take.

I would strongly encourage us to not take a server-based approach to this problem, however.  The minute you need hosting of application code vs. static webpages, the good, free options where multiple people from multiple institutions can update the content drops considerably.  This doesn't seem like the kind of thing that needs a server.  I think it is probably good enough to add a Sphinx extension that generates HTML redirect stub pages that just go to the appropriate place in the regular docs (or to standalone pages as Demitri suggests, if that's what we all agree to do, but that's just a matter of how the docs get built).  Additionally, this makes it work with a local copy of the docs, so the user could configure `online_docs_root` to where their local documentation is installed and have this system "just work".

Also, the version of astropy needs to be encoded in the URL somehow, as the descriptions may change with versions.  Or, we can just acquire a new number every time the documentation for an exception needs to significantly change (but I think the former is better).  Do we have a plan about how we are to host multiple versions of docs?  We'll need to sync with that.

With these two ideas in mind, the URLs would look something like:

   http://astropy.org/0.2/exc/1.html

or maybe with the package name:

   http://astropy.org/0.2/vo/exc/1.html

Or, really, we could create a hash that combines them all, if we want to make it shorter:

   http://astropy.org/afcd2813.html

but in my view, these urls are unlikely to get extremely long with this approach, and clearer is better (the hash idea also fails with a local copy, because in the remote case it has to work across multiple versions of the docs, but in the local case that doesn't make sense).

As an aside, many of the Linux terminals will automatically make URLs clickable -- but I think that is a function of the terminal emulator, not anything in the content stream.  IIRC from when I used to have a Mac, iTerm 2 had a configuration option for this.  Also, we can probably get IPython notebook to do this for us, if it doesn't already (I haven't tested -- but I suspect they'd gladly support a patch if need be.)

Mike

--
Michael Droettboom
http://www.droettboom.com/

[Erik Bray]

On Wed, Oct 3, 2012 at 12:17 AM, Demitri Muna <demitr...@gmail.com> wrote:

> Hi,
>
> On 2 Oct 2012, at 14:16, Erik Bray <erik....@gmail.com> wrote:
>
> I like it! I think this is a decent idea. A few things I might do
> differently though: I would much prefer to keep any error
> documentation closely associated with the code it relates to. I think
> it's already hard enough as it is to keep code and user documentation
> in sync. And having an entire separate set of documentation that
> needs to be referenced and and kept up to date could become
> problematic.
>
> I'm concerned about breaking the flow of the code - large amounts of
> documentation heavily interspersed with the code will make it impossible to
> read. I do think they should be kept separate. Keeping it in sync/matched is
> a little tricky, and I'm still pondering clean ways to do that.
>
> Another reason to keep them separate is that it will be *much* more
> convenient/easy to write and edit. Editing in-line marked up text is pretty
> much a non-starter I think.

At first I was thinking this would be no worse than the in-line API
documentation we already have. If well organized I don't see it as
such a hindrance. But I cede your point. That said I would rather
not have a completely separate documentation section for this. Better
to have exception help included in the main docs--possibly in an
appendix. That eliminates the need for a special server-- we can just
link to the sphinx docs that are already hosted online. And for the
correct version too.

I think that Mike's idea of a simple extension to generate shortened
links to various error pages will help too.

> In the interest of keeping the URLS as short as possible I actually looked
> into registering a Paraguay top level domain so we could have "astro.py",
> but the language and rules got a little complicated. (Anyone here live in
> Paraguay!?)

I vote against abusing ccTLDs. :)

[Michael Droettboom]

On Wed, Oct 3, 2012 at 11:54 AM, Erik Bray <erik....@gmail.com> wrote:

On Wed, Oct 3, 2012 at 12:17 AM, Demitri Muna <demitr...@gmail.com> wrote:

> Another reason to keep them separate is that it will be *much* more
> convenient/easy to write and edit. Editing in-line marked up text is pretty
> much a non-starter I think.

At first I was thinking this would be no worse than the in-line API
documentation we already have.  If well organized I don't see it as
such a hindrance.  But I cede your point.  That said I would rather
not have a completely separate documentation section for this.  Better
to have exception help included in the main docs--possibly in an
appendix.  That eliminates the need for a special server-- we can just
link to the sphinx docs that are already hosted online.  And for the
correct version too.

I've liked the middle ground that `vo` takes: The "exception help" content is in the docstring of an exception class, and all of those exception classes are in a separate module.  That way it doesn't interrupt the flow of the code that actually raises the exceptions, but it's still accessible by doing `ExceptionName?` in ipython (which wouldn't be the case if this only existed in the documentation tree).

Mike 

[Demitri Muna]

On Oct 3, 2012, at 11:54 AM, Erik Bray <erik....@gmail.com> wrote:

> I vote against abusing ccTLDs. :)

But it would have been *cool*. :) I wasn't seriously pursuing it.

Thanks to everyone for the comments and feedback. To address some points.

* Requiring an external server. I think we should serve these error pages (still coming up with a better name) on a server, for a couple of reasons. First, I don't think it's a good idea to install a server on someone's machine - certainly not Apache, but even a Python http server. I just don't want to open the door to security risks, and having to teach people how to set that up to access the pages is onerous. Even if the URLs were file:// leading to an absolute path, the actual URL will then be machine specific, preventing people from emailing them to others. They would almost certainly be very long. Also, we can't assume astropy *is* installed on the user's machine. They could very easily be logged into their linux cluster, and having people open a remote Firefox X window is a sure way to make sure people don't use it. I really think the lowest bar here is an externally hosted URL.

* Maintaining pages across versions & URLs. This occurred to me (with dread). We have to be careful to minimize the effort in maintaining this, but I think it's achievable. Pages that don't need to be changed between versions should be left alone, i.e. require *no* extra effort between releases. For this reason I'd recommend against including the release number in the URL - one page can easily live across many releases. On the other hand, if the URL includes the release but a back end server maps it to the right file (that is the same across releases), then that would be ok. More reason to offload this complexity to a back end server. For this reason I was thinking the same as Michael suggested, that each page get a number that is retired when the page is retired.

I know it's a little strange, but remotely hosted pages are actually the easiest solution for the *user* - they don't have to do *any* setup to get to them, and we don't have to make *any* assumptions of the user's environment (short of internet connectivity) to provide them.

* Custom exceptions. I do employ custom exceptions when it makes sense, but to generate potentially hundreds of these seems to me to abuse the notion of Python exceptions. If I need to throw a ValueError, that's what I should throw. Virtually no one will (should!) see that my custom Exception is a subclass, and I certainly don't want people writing try/excepts around that multitude.

* Including the pages in the documentation. Regardless of where they live, I don't believe these pages should be online as part of the documentation. It would be like having a section in the back of a city map (e.g. Thomas Map, A-Z) with pages that said "the doughnut shop you are trying to get to is actually one street over - turn left on Sepulveda here." It won't make any sense without context, and worse, will distract from the nice and lovely tutorials that are present. These are *highly context sensitive* descriptions, and frankly will repeat a lot of material. It won't be useful, and will in fact (I believe) be detrimental.

* Clickable links in the terminal. Well, for Mac users, this is pretty cool:
http://hints.macworld.com/article.php?story=20110911122108326

[Erik Bray]

On Wed, Oct 3, 2012 at 1:05 PM, Demitri Muna <demitr...@gmail.com> wrote:
> I know it's a little strange, but remotely hosted pages are actually the easiest solution for the *user* - they don't have to do *any* setup to get to them, and we don't have to make *any* assumptions of the user's environment (short of internet connectivity) to provide them.

I agree--I don't know how I feel about installing entire copies of the
documentation with the source code by default (though many projects do
this no problem).

> * Custom exceptions. I do employ custom exceptions when it makes sense, but to generate potentially hundreds of these seems to me to abuse the notion of Python exceptions. If I need to throw a ValueError, that's what I should throw. Virtually no one will (should!) see that my custom Exception is a subclass, and I certainly don't want people writing try/excepts around that multitude.

I wasn't suggesting using custom exception classes for every
exception. More like a factory function of some sort:
"astropy_exception(ValueError, 'Exception message...',
EXCEPTION_CODE)" Where EXCEPTION_CODE might be a string, a number, or
possibly even a reference to some object. I don't know yet. But it
would handle the details of constructing the correct URL for the
correct error number and the correct Astropy version.

> * Including the pages in the documentation. Regardless of where they live, I don't believe these pages should be online as part of the documentation. It would be like having a section in the back of a city map (e.g. Thomas Map, A-Z) with pages that said "the doughnut shop you are trying to get to is actually one street over - turn left on Sepulveda here." It won't make any sense without context, and worse, will distract from the nice and lovely tutorials that are present. These are *highly context sensitive* descriptions, and frankly will repeat a lot of material. It won't be useful, and will in fact (I believe) be detrimental.

That's why error help should go in an appendix. It shouldn't
interrupt the flow of the narrative section of the documentation, but
it's still part of the documentation. It also means we don't have to
worry about hosting it since we already have Sphinx documentation
hosting. Finally, it also makes the issue of "versions" easy to deal
with since we already build and release docs for each version of
Astropy (in fact, for ".dev" versions the aforementioned
astropy_exception() function can generate links to the latest build
version of the docs on readthedocs.org).

> * Clickable links in the terminal. Well, for Mac users, this is pretty cool:
> http://hints.macworld.com/article.php?story=20110911122108326

gnome-terminal has long done this too. And to address a question
someone rose about IPython notebook, it already automatically converts
URLs to links at least in markdown cells :)

Erik B.

[Michael Droettboom]

On Wed, Oct 3, 2012 at 1:05 PM, Demitri Muna <demitr...@gmail.com> wrote:

On Oct 3, 2012, at 11:54 AM, Erik Bray <erik....@gmail.com> wrote:

> I vote against abusing ccTLDs.  :)

* Requiring an external server. I think we should serve these error pages (still coming up with a better name) on a server, for a couple of reasons. First, I don't think it's a good idea to install a server on someone's machine - certainly not Apache, but even a Python http server. I just don't want to open the door to security risks, and having to teach people how to set that up to access the pages is onerous. Even if the URLs were file:// leading to an absolute path, the actual URL will then be machine specific, preventing people from emailing them to others. They would almost certainly be very long. Also, we can't assume astropy *is* installed on the user's machine. They could very easily be logged into their linux cluster, and having people open a remote Firefox X window is a sure way to make sure people don't use it. I really think the lowest bar here is an externally hosted URL.

That's probably fine -- as long as we're defining "server" as "anything that can serve static webpages".  While I think the ability to install a local copy of the docs is always going to be important for some people, they are in the minority, and it probably isn't worth the effort making this system we're talking about here work perfectly in that case.

 

* Maintaining pages across versions & URLs. This occurred to me (with dread). We have to be careful to minimize the effort in maintaining this, but I think it's achievable. Pages that don't need to be changed between versions should be left alone, i.e. require *no* extra effort between releases. For this reason I'd recommend against including the release number in the URL - one page can easily live across many releases. On the other hand, if the URL includes the release but a back end server maps it to the right file (that is the same across releases), then that would be ok. More reason to offload this complexity to a back end server. For this reason I was thinking the same as Michael suggested, that each page get a number that is retired when the page is retired.

But assuming the pages are part of the documentation build (though not part of the narrative), they will be built and handled with each release anyway.  I'm wary of having "another thing" off to the side that's versioned and deployed in a different way than the docs.  I think just putting the version in the URL is just simpler (doesn't require maintaining a mapping or having back-end server code running), and then, if the descriptions want to link to other parts of the documentation for greater detail, it will link to the version of the documentation that the user is running -- no potential for confusion there.

 

* Custom exceptions. I do employ custom exceptions when it makes sense, but to generate potentially hundreds of these seems to me to abuse the notion of Python exceptions. If I need to throw a ValueError, that's what I should throw. Virtually no one will (should!) see that my custom Exception is a subclass, and I certainly don't want people writing try/excepts around that multitude.

I'll concede on that in some cases -- though having specific exception types (appropriately subclassed from one of the built-in classes, of course), has been very useful for users of astropy.io.vo who want to deal with a particular exception type in their own way to account for the peculiarities of their own VO server.  It's much easier to catch a specific exception by type than to try to parse the message and/or fields of some exception object.  For this framework we're discussing here to work, we need a unique identifier for each bit of explanatory text that we want to attach to an exception.  If not the class of the exception, then, as Erik pointed out, it just has to be something else.

 

* Including the pages in the documentation. Regardless of where they live, I don't believe these pages should be online as part of the documentation. It would be like having a section in the back of a city map (e.g. Thomas Map, A-Z) with pages that said "the doughnut shop you are trying to get to is actually one street over - turn left on Sepulveda here." It won't make any sense without context, and worse, will distract from the nice and lovely tutorials that are present. These are *highly context sensitive* descriptions, and frankly will repeat a lot of material. It won't be useful, and will in fact (I believe) be detrimental.

I think Erik answered this quite well already.

Mike

 

* Clickable links in the terminal. Well, for Mac users, this is pretty cool:
http://hints.macworld.com/article.php?story=20110911122108326

Cheers,
Demitri

_________________________________________
Demitri Muna

Center for Cosmology and Particle Physics
New York University

http://scicoder.org

[Michael Droettboom]

On Wed, Oct 3, 2012 at 1:25 PM, Erik Bray <erik....@gmail.com> wrote:

And to address a question

someone rose about IPython notebook, it already automatically converts
URLs to links at least in markdown cells :)

That's cool.  Unfortunately, exception tracebacks aren't markdown cells.  It should be theoretically possible to add this to output cells, however, using the same approach that gnome-terminal etc. are using (I assume to just be a regex on things that look like URLs).

Mike

[Erik Bray]

Yup--didn't think of that I guess. And after a quick test, indeed it
does not render URLs in output cells as hyperlinks. Except to see a
pull request to IPython for this shortly :)

Erik B.

[Erik Bray]

Thy will be done: https://github.com/ipython/ipython/pull/2464

[Michael Droettboom]

Just tried this out.  Very nice.

Mike

[Erik Tollerud]

+1 from me as well on this general idea!

There is a slightly different approach that *might* work better: We
could actually support *both* rst and markdown if we link directly to
github's blob of the files - it's smart enough to render the file in
the correct format (see e.g.
https://github.com/eteq/astropy/blob/staging/test.rst and
https://github.com/eteq/astropy/blob/staging/test.markdown). Then we
wouldn't have sphinx fanciness available, but maybe that's ok for
simple stuff like this. Note that gets rid of the problem of in vs.
out of docs - it still should be in the astropy repo, but it could be
in, say, a "quickhelp" directory in the repository. This should still
be very easy for users to edit, because all they have to do is click
"edit" on the github page. Then we could just have
http://help.astropy.org be a simple service that redirects to the
appropriate file on github. This also solves the version problem,
because the commit number it accesses can be tied to the commit of the
version requested. e.g., ``http://astropy.org/0.1/vo/1`` would point
to ``quickhelp/vo/1.rst`` on commit
9847aa1412ef9ac337e7a2e8d998161d81fc4157 - that's the commit SHA for
v0.1.

If we don't want to go with that, though, I agree with Erik B and Mike
here that it makes sense to keep this in the astropy repo. But I also
see Demitri's point that these should not be reachable from the
standard doc pages - e.g., if you just go to docs.astropy.org, we
should make it so you never see these pages in the index or TOC or
anything like that. We should be able to do this pretty easily with
sphinx. We can also make it very easy for users to edit these pages
by adding a big link at the top that says "Edit this page" that points
immediately to the appropriate "edit" button on github - we actually
have something like this now. (See the "edit on github" link on the
far right of http://docs.astropy.org/en/latest/_generated/astropy.units.core.Unit.html#astropy.units.core.Unit
)

>> I vote against abusing ccTLDs. :)
>
> But it would have been *cool*. :) I wasn't seriously pursuing it.

Let's consider the matter further if we get an active astropy
contributor who lives in Paraguay :)



--
Erik

[Demitri Muna]

Hi,

On Oct 4, 2012, at 2:21 PM, Erik Tollerud <erik.t...@gmail.com> wrote:

> There is a slightly different approach that *might* work better: We
> could actually support *both* rst and markdown if we link directly to
> github's blob of the files - it's smart enough to render the file in
> the correct format (see e.g.
> https://github.com/eteq/astropy/blob/staging/test.rst and
> https://github.com/eteq/astropy/blob/staging/test.markdown).

I'm not married to one or the other, I just liked the idea of editing them directly on GitHub. Nice to see that it supports both.

> Note that gets rid of the problem of in vs.
> out of docs - it still should be in the astropy repo, but it could be
> in, say, a "quickhelp" directory in the repository.

Yes! "quickhelp"! That's the name. I love it. Each package can have a directory called "quickhelp" where the pages are located. (I still think that's simplest.) And yes, the versioning problem is solved by having every public release checked out next to the server.

> This should still
> be very easy for users to edit, because all they have to do is click
> "edit" on the github page.

By "users" I assume you mean "us", as I'm not expecting the larger community to edit these. :) But I like the idea of putting a link (or a form directly on the page) to say whether the page helped, wasn't helpful, or how it could be made more helpful. Or even the code that took them there so we can clarify things in the future.

> Then we could just have
> http://help.astropy.org be a simple service that redirects to the
> appropriate file on github.

I like the "help.astropy.org" name. I think it will confuse/distract the users though to take them to GitHub though. The help pages should be very clean and minimal - GitHub is too technical for the audience I'm aiming at.

I may not have made myself clear about the location of the pages - they should absolutely be in the repo. Just not in the docs.

[Erik Tollerud]

I personally don't like the idea of putting them directly in the
packages because putting anything other than code and data in the
packages can lead to significant headaches with distutils/distribute
and how it decides what to actually put in releases and installs and
such (see https://github.com/astropy/astropy/issues/403 for an example
of this sort of thing). What about a "quickhelp" directory in the
root of the astropy repo?

If we do it outside the docs, though, we can't build it as part of the
build_sphinx or related family of scripts, so that would force us to
point to the github page (e.g. exactly what you see with
https://github.com/eteq/astropy/blob/staging/test.rst). Unless you're
suggesting a web app that actually re-builds a second distinct set of
sphinx docs every time that directory is changed? If we did it that
way, I suppose you could even include the code for the app in the
"quickhelp" directory...

--
Erik

[Demitri Muna]

Hi,

On 4 Oct 2012, at 16:13, Erik Tollerud <erik.t...@gmail.com> wrote:

I personally don't like the idea of putting them directly in the
packages because putting anything other than code and data in the
packages can lead to significant headaches with distutils/distribute
and how it decides what to actually put in releases and installs and
such (see https://github.com/astropy/astropy/issues/403 for an example
of this sort of thing).  What about a "quickhelp" directory in the
root of the astropy repo?

Totally fine with that. The quickhelp directory structure would then just match the rest of the repo.

If we do it outside the docs, though, we can't build it as part of the
build_sphinx or related family of scripts, so that would force us to
point to the github page (e.g. exactly what you see with
https://github.com/eteq/astropy/blob/staging/test.rst).  Unless you're
suggesting a web app that actually re-builds a second distinct set of
sphinx docs every time that directory is changed? If we did it that
way, I suppose you could even include the code for the app in the
"quickhelp" directory...

I was suggesting a standalone web app, and since it was my idea volunteered to write it. I don't see what the sphinx docs have to do with it though - the quickhelp directory would only contain the .rst pages, and nothing need generate anything based on them. The web app will serve the pages with whatever CSS we make for it. But this will have to be hosted/served somewhere, and as before, I'm happy to host it here at NYU.

I'm happy to put the quickhelp web app code in the top level of the quickhelp directory.

Cheers,

Demitri

_________________________________________
Demitri Muna

Center for Cosmology and Particle Physics
New York University

http://scicoder.org/

[Erik Tollerud]

Ah, so then the question is just whether or not we want to be able to
use sphinx features like doing e.g., typing "`astropy.units.Unit`" and
having it figure out what doc page to point to. If we want to be able
to use sphinx features like that on these pages, then we would want to
build it with the docs so that sphinx runs on it. But if we consider
that unimportant, then what you're suggesting would be just fine (and
probably simpler). PersonalIy, I don't really care that much either
way - anyone else have a strong opinion on the matter (besides
Demitri, whos opinion I think we know on this one :).

--
Erik

[Michael Droettboom]

I think being able to link to other parts of the documentation is critically important, and the only reliable way to do that (since Sphinx docs don't really have internal permalinks) is to build it as part of the docs.  I think as long as these pages are "orphaned" or in an appendix, they won't intrude too much there.  Plus, they'll be searchable in the Sphinx search box, which I also see as a plus.

Mike

[Thomas Robitaille]

I was going to say the same - we should just put them in the normal docs, and declare them as orphans. Then they don't appear in the TOC, but it makes sense they would still appear in the search results.

What we *could* have is have a separate app that just acts as a URL shortener - so if we want to store these pages in their respective sub-packages, we could have the exception have a URL like http://help.astropy.org/E322 which then redirects to the appropriate page on http://docs.astropy.org (e.g. http://docs.astropy.org/io/vo/quickhelp/E322)

Cheers,

Tom

[Michael Droettboom]

To avoid any server side code, as I mentioned earlier, we could just a have a sphinx extension that generates these "stubs" at the top-level as HTML redirect files.  Then they will work even on a webserver that can only serve static pages.

Mike

[Erik Bray]

On Mon, Oct 8, 2012 at 8:56 AM, Michael Droettboom <mdb...@gmail.com> wrote:
> To avoid any server side code, as I mentioned earlier, we could just a have
> a sphinx extension that generates these "stubs" at the top-level as HTML
> redirect files. Then they will work even on a webserver that can only serve
> static pages.

+1 to this.