API links in the docs?
Hi all, It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc. I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs. Nathan
Hi Nathan,
Not sure I understand -- is the link to the API docs not going? Is
api.rst not being built? Are there links to things in the docs
scattered about that are dead?
-Matt
On Sun, Jul 15, 2012 at 7:24 PM, Nathan Goldbaum
Hi all,
It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc.
I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs.
Nathan _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Sorry for not being clearer. It's that there are dead links scattered throughout the docs. I've placed a build of the docs at http://ucolick.org/~goldbaum/files/build/html/ If you compare this page: http://ucolick.org/~goldbaum/files/build/html/analyzing/objects.html to the equivalent in the current version of the docs: http://yt-project.org/doc/analyzing/objects.html You'll see that links to api entries don't work. In the 2.3 docs the api entries pointed to a page like this: http://yt-project.org/doc/reference/api/generated/yt.data_objects.data_conta... On 7/15/12 8:33 PM, Matthew Turk wrote:
Hi Nathan,
Not sure I understand -- is the link to the API docs not going? Is api.rst not being built? Are there links to things in the docs scattered about that are dead?
-Matt
On Sun, Jul 15, 2012 at 7:24 PM, Nathan Goldbaum
wrote: Hi all,
It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc.
I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs.
Nathan _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Hi Nathan,
I can't remember if the current development tip does this or not, but
one idea that had been floated was removing toctree entries for
auto-generated docs. This was to experiment with how search
functions. It's likely that if toctree entries aren't emitted by the
API docs, they won't be available for cross-linking.
-Matt
On Sun, Jul 15, 2012 at 8:46 PM, Nathan Goldbaum
Sorry for not being clearer. It's that there are dead links scattered throughout the docs.
I've placed a build of the docs at http://ucolick.org/~goldbaum/files/build/html/
If you compare this page: http://ucolick.org/~goldbaum/files/build/html/analyzing/objects.html
to the equivalent in the current version of the docs: http://yt-project.org/doc/analyzing/objects.html
You'll see that links to api entries don't work. In the 2.3 docs the api entries pointed to a page like this:
http://yt-project.org/doc/reference/api/generated/yt.data_objects.data_conta...
On 7/15/12 8:33 PM, Matthew Turk wrote:
Hi Nathan,
Not sure I understand -- is the link to the API docs not going? Is api.rst not being built? Are there links to things in the docs scattered about that are dead?
-Matt
On Sun, Jul 15, 2012 at 7:24 PM, Nathan Goldbaum
wrote: Hi all,
It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc.
I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs.
Nathan _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Ok, well if that means the docstrings don't make it into the html docs, I think we need to figure out another solution. Is it possible to include the toctree entries but on one monolithic page or a few pages covering different API categories? -Nathan On 7/15/12 8:48 PM, Matthew Turk wrote:
Hi Nathan,
I can't remember if the current development tip does this or not, but one idea that had been floated was removing toctree entries for auto-generated docs. This was to experiment with how search functions. It's likely that if toctree entries aren't emitted by the API docs, they won't be available for cross-linking.
-Matt
On Sun, Jul 15, 2012 at 8:46 PM, Nathan Goldbaum
wrote: Sorry for not being clearer. It's that there are dead links scattered throughout the docs.
I've placed a build of the docs at http://ucolick.org/~goldbaum/files/build/html/
If you compare this page: http://ucolick.org/~goldbaum/files/build/html/analyzing/objects.html
to the equivalent in the current version of the docs: http://yt-project.org/doc/analyzing/objects.html
You'll see that links to api entries don't work. In the 2.3 docs the api entries pointed to a page like this:
http://yt-project.org/doc/reference/api/generated/yt.data_objects.data_conta...
On 7/15/12 8:33 PM, Matthew Turk wrote:
Hi Nathan,
Not sure I understand -- is the link to the API docs not going? Is api.rst not being built? Are there links to things in the docs scattered about that are dead?
-Matt
On Sun, Jul 15, 2012 at 7:24 PM, Nathan Goldbaum
wrote: Hi all,
It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc.
I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs.
Nathan _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Probably, but I won't be able to really do this in detail for about a
week and change. If someone else wants to experiment with this that
would be great!
-Matt
On Sun, Jul 15, 2012 at 8:52 PM, Nathan Goldbaum
Ok, well if that means the docstrings don't make it into the html docs, I think we need to figure out another solution. Is it possible to include the toctree entries but on one monolithic page or a few pages covering different API categories?
-Nathan
On 7/15/12 8:48 PM, Matthew Turk wrote:
Hi Nathan,
I can't remember if the current development tip does this or not, but one idea that had been floated was removing toctree entries for auto-generated docs. This was to experiment with how search functions. It's likely that if toctree entries aren't emitted by the API docs, they won't be available for cross-linking.
-Matt
On Sun, Jul 15, 2012 at 8:46 PM, Nathan Goldbaum
wrote: Sorry for not being clearer. It's that there are dead links scattered throughout the docs.
I've placed a build of the docs at http://ucolick.org/~goldbaum/files/build/html/
If you compare this page: http://ucolick.org/~goldbaum/files/build/html/analyzing/objects.html
to the equivalent in the current version of the docs: http://yt-project.org/doc/analyzing/objects.html
You'll see that links to api entries don't work. In the 2.3 docs the api entries pointed to a page like this:
http://yt-project.org/doc/reference/api/generated/yt.data_objects.data_conta...
On 7/15/12 8:33 PM, Matthew Turk wrote:
Hi Nathan,
Not sure I understand -- is the link to the API docs not going? Is api.rst not being built? Are there links to things in the docs scattered about that are dead?
-Matt
On Sun, Jul 15, 2012 at 7:24 PM, Nathan Goldbaum
wrote: Hi all,
It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc.
I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs.
Nathan _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Looks like the issue is at line 244 of conf.py: autosummary_generate = glob.glob("api.rst") should be: autosummary_generate = glob.glob("api/api.rst") The corrected will autogenerate all of the api pages as expected. I think we should turn this on but we should think about a way to include the api docs in a saner way. Maybe there's a better way to use sphinx autodoc? On 7/15/12 8:54 PM, Matthew Turk wrote:
Probably, but I won't be able to really do this in detail for about a week and change. If someone else wants to experiment with this that would be great!
-Matt
On Sun, Jul 15, 2012 at 8:52 PM, Nathan Goldbaum
wrote: Ok, well if that means the docstrings don't make it into the html docs, I think we need to figure out another solution. Is it possible to include the toctree entries but on one monolithic page or a few pages covering different API categories?
-Nathan
On 7/15/12 8:48 PM, Matthew Turk wrote:
Hi Nathan,
I can't remember if the current development tip does this or not, but one idea that had been floated was removing toctree entries for auto-generated docs. This was to experiment with how search functions. It's likely that if toctree entries aren't emitted by the API docs, they won't be available for cross-linking.
-Matt
On Sun, Jul 15, 2012 at 8:46 PM, Nathan Goldbaum
wrote: Sorry for not being clearer. It's that there are dead links scattered throughout the docs.
I've placed a build of the docs at http://ucolick.org/~goldbaum/files/build/html/
If you compare this page: http://ucolick.org/~goldbaum/files/build/html/analyzing/objects.html
to the equivalent in the current version of the docs: http://yt-project.org/doc/analyzing/objects.html
You'll see that links to api entries don't work. In the 2.3 docs the api entries pointed to a page like this:
http://yt-project.org/doc/reference/api/generated/yt.data_objects.data_conta...
On 7/15/12 8:33 PM, Matthew Turk wrote:
Hi Nathan,
Not sure I understand -- is the link to the API docs not going? Is api.rst not being built? Are there links to things in the docs scattered about that are dead?
-Matt
On Sun, Jul 15, 2012 at 7:24 PM, Nathan Goldbaum
wrote: Hi all,
It seems that the recent changes to the docs have broken the internal links to api references. Since the docstrings are inside the api references, this means the docstrings don't show up in new builds of the docs. I'm not sure if this is a sphinx issue or an issue with the tip of yt-doc.
I think there was some discussion about consolidating the api reference pages, which I am in favor of, but we should still make sure the docstrings are available inside the html docs.
Nathan _______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
_______________________________________________ yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
yt-dev mailing list yt-dev@lists.spacepope.org http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org
Hi Nathan,
On Sun, Jul 15, 2012 at 10:50 PM, Nathan Goldbaum
Looks like the issue is at line 244 of conf.py:
autosummary_generate = glob.glob("api.rst")
should be:
autosummary_generate = glob.glob("api/api.rst")
The corrected will autogenerate all of the api pages as expected.
I think we should turn this on but we should think about a way to include the api docs in a saner way. Maybe there's a better way to use sphinx autodoc?
Unfortunately, I don't know what that is. Using the non-autosummary (and non-numpydoc) would mean rewriting all of our docstrings, and also getting rid of the full-length descriptions of individual routines. So while we could do that, we need to know that's what wer'e getting into. That's a decision that's certainly worth revisiting, but I do think that we benefit from the relative depth of individual routine documentation with the autosummary style. If it's really just the indexing that is an issue, then perhaps that should be addressed separately -- but it might have to be addressed via queries to the sphinx mailing list. -Matt
participants (2)
-
Matthew Turk
-
Nathan Goldbaum