Code API link shows index page for Noetic but other distro seems to work

ros-infrastructure / rosdoc_lite

A light-weight version of rosdoc that does not rely on ROS infrastructure for crawling packages.

10 stars 31 forks source link

Code API link shows index page for Noetic but other distro seems to work #98

Open 130s opened 4 years ago

130s commented 4 years ago

Screenshot from 2020-06-12 16-13-35

tfoote commented 4 years ago

This looks like an issue with the doc jobs.

http://build.ros.org/view/Ndoc/job/Ndoc__ros_comm__ubuntu_focal_amd64/15/consoleFull#console-section-26

I see that it appears to be missing epydoc and dot as dependencies.

Looking a little deeper it appears we have a bit of a problem that epydoc doesn't support python3. This group switch to sphinx-epytext https://github.com/tulip-control/tulip-control/issues/194

https://pypi.org/project/sphinx-epytext/

tfoote commented 4 years ago

@sloretz FYI this means that a large fraction of noetic doc jobs may be missing.

ros-discourse commented 3 years ago

This issue has been mentioned on ROS Discourse. There might be relevant details there:

https://discourse.ros.org/t/migration-of-docs-ros-org-content-into-en-prefix/16829/5

gavanderhoorn commented 3 years ago

Apparently twisted/pydoctor is a Python 3 compatible (spiritual?) successor to epydoc.

There are a few epydoc clones available on Github (such as nltk/epydoc), but they are not necessarily all complete.

Seeing as this will be "only" needed to get Noetic doc jobs working again: is a structural (ie: completely future proof) replacement needed, or would a little less clean, but nevertheless working doc generation for Noetic be sufficient?

(note: I'm not volunteering here, just want to get the requirements/constraints clear)

Edit: pydoctor may perhaps not be as much of a drop-in replacement after all, but I haven't tested it yet.

tfoote commented 3 years ago

If there's a drop in replacement that will work we'd be happy to accept PRs to integrate it instead. However with the relatively small number of packages effected and almost all of them quite stable since Melodic I would recommend most users to simply use the melodic docs.

We have developed a new system for ROS 2 which means work focused here will not be reused down the line.

rgov commented 2 years ago

Would it be perhaps a few minutes' shell scripting to get a symlink in each directory to the Melodic docs? I've been hitting this for over a year and it wasn't apparent to me that such a simple workaround is available, and it took some sleuthing to land at this issue.

tristanlatr commented 2 years ago

Hello,

If I may, I'de suggest you to use, pydoctor. It supports Epytext and it's actively used and maintained by the twisted community. If your build is working with epydoc, it should not be hard to make to work with pydoctor since their CLI interface largely ressembles.

Tell me what you think,

Thanks

MatthijsBurgh commented 2 years ago

I have made some progress on migrating epydoc to python3 and making it compatible with new version of its dependencies. See https://github.com/MatthijsBurgh/epydoc

The html generation should be fully working. Latex generation is not fully working. As there has been a significant change in docutils. Which I haven't been able yet to get it fully working. As this isn't working I haven't released it yet. (Also I am not that experienced with releasing packages)

Any contribution is appreciated.

gavanderhoorn commented 2 years ago

Latex generation is not fully working.

do ROS 1 docs need Latex generation?

HTML-based C++ and Python documentation should go quite far I believe.

MatthijsBurgh commented 2 years ago

do ROS 1 docs need Latex generation?

HTML-based C++ and Python documentation should go quite far I believe.

No, I don't think it needs Latex. (It is just my personal goal to fully restore it.)

With some community contributions we could get epydoc to release state. Which can bring back a lot of documentation pages.

gavanderhoorn commented 2 years ago

With some community contributions we could get epydoc to release state.

what would still be needed?

MatthijsBurgh commented 2 years ago

I think the minimal ToDo's are:

convert scripts to entry points (Should not be too much work)
Evaluate and reorder repo folder structure (Work depending on the evaluation, but should be too much work either)
Implement solid CI in GH actions (Should not be too much work)
Check, update and document release procedure for pip (Already an entry in the makefile, but I can't judge if that is good/sufficient/up-to-date) (Need to get access to the pypi entry of epydoc, https://pypi.org/project/epydoc/, from the original author)
Documentation/manual html generation working and automated (It has been some time, since I tried this. I am not sure about the state of the generation. When working, this would only require the automation. But could also require some work to get generation fully working.)

tristanlatr commented 2 years ago

@MatthijsBurgh, impressive work trying to restore epydoc! Good job.

130s commented 2 years ago

From the original post,

NG http://docs.ros.org/noetic/api/rosmaster/html

This (and many others I just tried) still seems to be the case. However,

OK http://docs.ros.org/en/noetic/api/roscpp/html/ :shrug: