Fix documentation build errors (while building from the docs folder).

[sandeepd-nv]

Change into the legate.core/docs/legate/core folder and then run make html. You'll get the following error...

legate.core/docs/legate/core/source/BUILD.md:40:'myst' cross-reference target not found: 'dependency-listing' [myst.xref_missing]

Fixing this error will lead to other errors. Please fix them all.

[manopapad]

I tried reproducing this. I am not getting the same error, but doc building is also failing for me:

computelab-frontend-3:/home/scratch.mpapadakis_sw/legate.core/docs/legate/core> make html
Running Sphinx v5.3.0
Adding copy buttons to code blocks...
locale_dir /home/scratch.mpapadakis_sw/legate.core/docs/legate/core/source/locales/en/LC_MESSAGES does not exists
[autosummary] generating autosummary for: BUILD.md, CONTRIBUTING.md, README.md, api/allocation.rst, api/classes.rst, api/index.rst, api/operation.rst, api/routines.rst, api/runtime.rst, api/shape.rst, api/store.rst, index.rst, versions.rst

Traceback (most recent call last):
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/ext/autosummary/generate.py", line 395, in generate_autosummary_docs
    name, obj, parent, modname = import_by_name(entry.name)
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/ext/autosummary/__init__.py", line 661, in import_by_name
    raise ImportExceptionGroup('no module named %s' % ' or '.join(tried), exceptions)
sphinx.ext.autosummary.ImportExceptionGroup: no module named legate.core.Library.get_c_header

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/events.py", line 94, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/ext/autosummary/__init__.py", line 811, in process_generate_options
    generate_autosummary_docs(genfiles, suffix=suffix, base_path=app.srcdir,
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/ext/autosummary/generate.py", line 400, in generate_autosummary_docs
    name, obj, parent, modname = import_ivar_by_name(entry.name)
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/ext/autosummary/__init__.py", line 720, in import_ivar_by_name
    real_name, obj, parent, modname = import_by_name(name, prefixes, grouped_exception)
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/ext/autosummary/__init__.py", line 661, in import_by_name
    raise ImportExceptionGroup('no module named %s' % ' or '.join(tried), exceptions)
sphinx.ext.autosummary.ImportExceptionGroup: no module named legate.core.Library

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/application.py", line 262, in __init__
    self._init_builder()
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/application.py", line 335, in _init_builder
    self.events.emit('builder-inited')
  File "/home/scratch.mpapadakis_sw/miniconda3/envs/legate/lib/python3.9/site-packages/sphinx/events.py", line 105, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function process_generate_options at 0x7f9d75350790> for event 'builder-inited' threw an exception (exception: no module named legate.core.Library)

Extension error (sphinx.ext.autosummary):
Handler <function process_generate_options at 0x7f9d75350790> for event 'builder-inited' threw an exception (exception: no module named legate.core.Library)
make: *** [Makefile:43: html] Error 2

[sandeepd-nv]

sphinx.ext.autosummary.ImportExceptionGroup: no module named legate.core.Library

@manopapad I think you need to build and install the legate.core library before you can build the documentation. See if running ./install.py --docs helps.

[manopapad]

I think you need to build and install the legate.core library before you can build the documentation. See if running ./install.py --docs helps.

I did install.py --docs first, then make html. Same error.

[marcinz]

The following diff fixes the problem for me:

diff --git a/README.md b/README.md
index 2edcbec..48f8137 100644
--- a/README.md
+++ b/README.md
@@ -473,6 +473,6 @@ documentation](https://nv-legate.github.io/legate.core).
 We recommend starting by experimenting with at least one Legate application
 library to test out performance and see how Legate works. If you are interested
 in building your own Legate application library, we recommend that you
-investigate our [Legate Hello World application library](examples/hello) that
+investigate our `Legate Hello World application library <examples/hello>`_ that
 provides a small example of how to get started developing your own drop-in
 replacement library on top of Legion using the Legate Core library.
diff --git a/docs/legate/core/source/conf.py b/docs/legate/core/source/conf.py
index efa5cc9..e7a28ce 100644
--- a/docs/legate/core/source/conf.py
+++ b/docs/legate/core/source/conf.py
@@ -80,6 +80,7 @@ mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"

 pygments_style = "sphinx"

+myst_heading_anchors = 3

 def setup(app):
     app.add_css_file("params.css")

I am not sure if we should have a full link for the hello world example. What I added here is probably not going to work. @bryevdv, what is the best way to link to legate.core directories?

[marcinz]

I created #655 for now. Verified to work on my machine. @sandeepd-nv, could you check as well?

[sandeepd-nv]

@marcinz I applied your patch locally and it fixed the build for me. Thanks!

[bryevdv]

FWIW I am unable to reproduce this problem locally on my linux workstation on latest branch-23.05

build succeeded.

The HTML pages are in build/html.

Build finished in 10 seconds

I think more detailed information about environments would be needed to try and figure out why.

Edit: OK I had an older version of myst-parser installed, after a pip install -U myst-parser I do see the same error

[marcinz]

@sandeepd-nv I commited a fix for these issues.

[marcinz]

Fixed by #655