search

odlgroup / odl

Operator Discretization Library https://odlgroup.github.io/odl/
Mozilla Public License 2.0
368 stars 105 forks source link

Links to attributes in API doc broken #1058

Open kohr-h opened 7 years ago

kohr-h commented 7 years ago

Apparently the ~30000 warnings issued by Sphinx are not just bogus but point to some grave issue with the way we generate the API doc, or with Numpydoc. I don't know the source of the problem, but the effect is that none of the internal links to attributes or methods in the API doc work. This seems to have happened in the switch from Sphinx 1.5 to 1.6, but I'm not sure.

adler-j commented 7 years ago

Well that sucks. Have you verified that the API doc actually creates all of the auxillary files that we need?

kohr-h commented 7 years ago

Looks OK to me in the last build.

So what should we do about it? The best short-term strategy would probably be to use Sphinx <1.6 (and make sure that it actually works there).

adler-j commented 7 years ago

I'll have to agree with you there. Long therm this whole generating fake files thing is a huge hack, sadly it is not our fault but the fault is with the sphinx/autodoc guys and I'm not quite sure how to solve it locally.

My overall experience with developing the docs has been rather bad, to say the least. I'd estimate that I've easily spent several full time weeks getting the doc working and even then it is a full on hack that keeps breaking once every other month. I'd be very much in favor of changing to some other framework if we can find anything that works, at all. An alternative would be to somehow remove the dependency on autodoc which is what's causing all of this trouble.

kohr-h commented 7 years ago

Problem for me is that I barely understand the whole pile of rubble on the surface, so I cannot be very helpful other than googling for alternatives or check out how other projects do it.

adler-j commented 7 years ago

Problem for me is that I barely understand the whole pile of rubble on the surface,

Sadly, noone does.

At its core, the problem is that Sphinx has no built in way of automatically generating the API doc (i.e. generate one page for each method), instead we need to depend on autosummary/autodoc, which partially solves the problem. I.e. it can generate one page per method, but you need to give it the modules. Well then, to solve that, we have the generate_doc.py script, which generates the doc. All in all this becomes a huge mess.

One way which would perhaps be doable would be to move all logic into generate_doc.py and scrap autodoc totally.

so I cannot be very helpful other than googling for alternatives or check out how other projects do it.

If you find any, I'd be happy to hear about it.

kohr-h commented 7 years ago

If you find any, I'd be happy to hear about it.

The only thing I can find is apidoc, which seems to be intended for the same purpose as our generate_doc script.

Some random links: https://stackoverflow.com/questions/29385564/customize-templates-for-sphinx-apidoc https://stackoverflow.com/questions/10343998/sphinx-public-api-documentation https://github.com/sphinx-doc/sphinx/blob/master/sphinx/apidoc.py

kohr-h commented 7 years ago

The situation seems to have improved again. Documentation pages and internal links work again, just the parent attributes are not linked properly. I guess we can relax a bit for now.