ROS2 package demo 11 - more fun with intersphinx

After much experimenting, I learned that the sphinx role :any: will link to intersphinx content. If I set that as the default role, then links like this work:

`fqdemo_nodes:index`

I’m trying to understand why the :ref:python:comparisons link works. AFAICT, links of type std:label are found by :ref:, others are not.

How about :doc:? It works with std:doc types. Tested with fqdemo_nodes.

I faced this again. What I discovered is that the title I was using used ==== to mark the title, as did the included document. When I used different characters, the issue went away.

The sphinx documentation leads me to believe that the :titlesonly: option is supposed to fix this, but I could not make it work.

Folder reorganization

I figured out how to organize things to use a generated folder for items I am likely to create, and not require that doc/docs structure. Implemented in fqdemo and fqdemo_msgs so far.

Python documentation

The html for fqdemo_nodes package looks funny. AFAICT I am not getting the correct Module contents.

The rst looks like this:

Module contents
---------------

.. automodule:: fqdemo_nodes
   :members:
   :undoc-members:
   :show-inheritance:

But all I see is:

Module contents

This is module-level documentation for fqdemo_nodes. The docstring must appear before any python statements, including include types.

I added some content to init.py for the package, that then appeared. I guess that is the intent of Module contents.

But how do I get somethin more useful in the whole document? It starts with:

fqdemo_nodes package
Submodules

    fqdemo_nodes.PySubPub module
        Overview

Module contents

which is pretty boring. Is this being generated by rosdoc2? I believe this comes from the sphinc-apidoc templates. See https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html.

Looking at the apidoc templates, I see an option to put the module documentation first. See –module-first here

Moving conf.py and other doc-related files.

The rosdoc2 docs assume assume that conf.py will be in the doc folder. I know more now, let me try to move it there.

apidoc is passed a directory for the “package” to document. By default, this is /. You can also pass package_src in rosdoc2.yaml to override this.

What is the relationship of that to sys.path? I believe that apidoc is given a file path, while autodoc uses sys.path. Note that in the wrapped conf.py, package_src_directory is used both to call apidoc, and to append to sys.path.

Fixing file locations for fqdemo_nodes

I cannot use my file assumptions on fqdemo_nodes, because the exhale output will be going directly into a subdirectoty of doc. See this explanation. So instead I need to modify fqdemo.