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

[130s]

• NG http://docs.ros.org/noetic/api/rosmaster/html
• ok http://docs.ros.org/melodic/api/rosmaster/html
• ok http://docs.ros.org/kinetic/api/rosmaster/html

[tfoote]

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 tulip-control/tulip-control#194

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

[tfoote]

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

[ros-discourse]

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]

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]

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]

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]

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]

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]

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]

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]

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

what would still be needed?

[MatthijsBurgh]

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]

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

[130s]

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/ 🤷