Various errors in docutils doctree and rst formatting

[eirrgang]

Errors remain in the sphinx build. I think the current errors are all due to .rst document syntax and doctree structure.

If I am mistaken, please attach examples in #2905. I think all of the examples provided by Matteo were addressed.

follow up to https://github.com/radical-cybertools/radical.pilot/issues/2905#issuecomment-1546737816

Example error output

• at HEAD: d9c4f26393d3a6eadd6587a38bb52deb7827d6a5
• suppressing nbsphinx errors

building [html]: targets for 44 source files that are out of date
updating environment: [new config] 44 added, 0 changed, 0 removed
reading sources... [100%] user_guide/simple_bot_multi                                                                                                                                                                                                
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/machconf.rst:121: WARNING: download file not readable: /Users/eric/develop/PycharmProjects/radical.pilot/src/radical/pilot/configs/resource_xsede.json
../CHANGES.md:1819: ERROR: Document may not end with a transition.
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/resources.rst:46: WARNING: download file not readable: /Users/eric/develop/PycharmProjects/radical.pilot/src/radical/pilot/configs/resource_fub.json
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/resources.rst:314: WARNING: download file not readable: /Users/eric/develop/PycharmProjects/radical.pilot/src/radical/pilot/configs/resource_radical.json
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/resources.rst:329: WARNING: download file not readable: /Users/eric/develop/PycharmProjects/radical.pilot/src/radical/pilot/configs/resource_radical.json
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/resources.rst:344: WARNING: download file not readable: /Users/eric/develop/PycharmProjects/radical.pilot/src/radical/pilot/configs/resource_radical.json
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/testing.rst:34: ERROR: Malformed table.

+-------------------------------------------+-------------------------------------+
| Environment Variable                      | What                                |
+===========================================+=====================================+
| ``RADICAL_PILOT_TEST_REMOTE_RESOURCE``    | Name (key) of the resource.         |
+-------------------------------------------+-------------------------------------+
| ``RADICAL_PILOT_TEST_REMOTE_SSH_USER_ID`` | User ID on the remote system.       |
+-------------------------------------------+-------------------------------------+
| ``RADICAL_PILOT_TEST_REMOTE_SSH_USER_KEY``| SSH key to use for the connection.  |
+-------------------------------------------+-------------------------------------+
| ``RADICAL_PILOT_TEST_REMOTE_WORKDIR``     | Work directory on the remote system.|
+-------------------------------------------+-------------------------------------+
| ``RADICAL_PILOT_TEST_REMOTE_CORES``       | Number of cores to allocate.        |
+-------------------------------------------+-------------------------------------+
| ``RADICAL_PILOT_TEST_REMOTE_NUM_CUS``     | Number of Tasks to run.     |
+-------------------------------------------+-------------------------------------+
| ``RADICAL_PILOT_TEST_TIMEOUT``            | Test timeout in minutes.            |
+-------------------------------------------+-------------------------------------+
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/00_getting_started.rst:207: WARNING: Title underline too short.

Executing the Example
-------------------
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/00_getting_started.rst:207: WARNING: Title underline too short.

Executing the Example
-------------------
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/multicore.rst:23: WARNING: Include file '/Users/eric/develop/PycharmProjects/radical.pilot/examples/misc/running_mpi_executables.py' not found or reading it failed
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/eric/develop/PycharmProjects/radical.pilot/docs/source/_themes/armstrong/README.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/intro.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/profiles.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/resources.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/async.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/callbacks.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/condor_grids.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/disconnect_reconnect.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/errorhandling.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/multicore.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/multiple_commands.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/remote_hpc_pilots.rst: WARNING: document isn't included in any toctree
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/simple_bot_multi.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] user_guide/simple_bot_multi                                                                                                                                                                                                 
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/overview.rst:250: WARNING: undefined label: 'chapter_profiles'
/Users/eric/develop/PycharmProjects/radical.pilot/docs/source/user_guide/02_failing_tasks.rst:8: WARNING: undefined label: 'task_state_model'
generating indices... genindex py-modindex done
highlighting module code... [100%] radical.pilot.utils.session                                                                                                                                                                                       
writing additional pages... search done
copying images... [100%] user_guide/11_containerized_compute_tasks_2.png                                                                                                                                                                             
copying downloadable files... [100%] ../../examples/10_pre_and_post_exec.py                                                                                                                                                                          
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 26 warnings.

[eirrgang]

It is not clear to me whether the the extra files are supposed to be in the doctree or whether they are either stale or works in progress. I don't know what the undefined labels are supposed to point to.

[mturilli]

Hi @eirrgang , yes, I think they were stale. Please have a look at devel and the new docs/source, rendered at https://radicalpilot.readthedocs.io/en/devel/. That is the new documentation we have been working on for a while. Feedback would be more than welcome!