How to disable, or ignore make doc errors

[PhilipDeegan]

with version 5.0.2 from

https://download.open-mpi.org/release/open-mpi/v5.0/openmpi-5.0.2.tar.bz2

During make, I am seeing the following error

make[1]: Entering directory '/io/ompi/docs'
  MKDIR    prrte-rst-content
  MKDIR    schizo-ompi-rst-content
  COPY RST source files
  COPY RST source files
  GENERATE HTML docs
Running Sphinx v7.2.6

Extension error:
Could not import extension recommonmark (exception: No module named 'recommonmark')
make[1]: *** [Makefile:2712: _build/man/ompi-wrapper-compiler.1] Error 2
make[1]: Leaving directory '/io/ompi/docs'
make: *** [Makefile:1533: all-recursive] Error 1

I'm not really concerned that docs is failing, so it would be nice to not count this is a critical failure, how can I ignore this?

[PhilipDeegan]

pip installing recommonmark seems to resolve this issue, but again, I have no need for these things

[jsquyres]

Normally, it shouldn't decide to re-build the docs if they're already present -- and they're already present in the tarball. Can you send some additional information?

• stdout/stderr from running configure
• config.log
• the output from make V=1

Additionally, if you don't care about tracking this down, you can ./configure --disable-sphinx.

[PhilipDeegan]

@jsquyres

Thanks for the response

Normally, it shouldn't decide to re-build the docs if they're already present

I had a look at the configure file briefly and to me, with my limited understanding of configure/autotools it looks like it will try to install the docs if the "MPI_T.3" file is found. The file does exist in the tarball

I will post the logs later when I get a chance to run it all again

printf %s "checking if pre-built docs are available... " >&6; }
    if test -f "$srcdir/docs/man/MPI_T.3"
then :
  oac_install_docs=1
           { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: yes" >&5
printf "%s\n" "yes" >&6; }
else $as_nop
  oac_install_docs=0
           { printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: no" >&5
printf "%s\n" "no" >&6; }

[jsquyres]

The file does exist in the tarball

Hmm -- I see that file in the tarball:

$ wget https://download.open-mpi.org/release/open-mpi/v5.0/openmpi-5.0.2.tar.bz2
...output snipped...
2024-02-16 08:39:26 (9.56 MB/s) - ‘openmpi-5.0.2.tar.bz2’ saved [29735046/29735046]
$ tar tf openmpi-5.0.2.tar.bz2 | grep docs/man/MPI_T.3
openmpi-5.0.2/docs/man/MPI_T.3

Are you seeing different output from configure? I.e., are you seeing:

checking if pre-built docs are available... no

?

And if so, how is that possible? Is docs/man/MPI_T.3 really not in your tarball?

[PhilipDeegan]

it is in the tarball, which I why I think the script looks a bit odd

configure:57527: checking if pre-built docs are available
configure:57532: result: yes

[jsquyres]

The script is auto-generated; it's inevitable that the formatting is weird. The source for that check is over here:

• https://github.com/open-mpi/oac/blob/main/oac_setup_sphinx.m4#L28-L46
• Which is instantiated (called) by https://github.com/open-mpi/ompi/blob/main/configure.ac#L1071-L1072

Can you send all the information I asked for in https://github.com/open-mpi/ompi/issues/12333#issuecomment-1943983134?

[PhilipDeegan]

browsable here, this was generated via a docker container of a somewhat modified nvidia/cuda:12.3.0-devel-ubuntu22.04 image

config.log other two requests are embedded together here

you can see the build.sh script how all this was generated

[jsquyres]

I think I see what's happening here. I think we don't have a comprehensive-enough configure test.

Specifically, we found the pre-built docs, but we also found Sphinx, we the assumption is "build the docs if we need to". Due to some complicated make dependencies, we determined "yes, we need to build the docs" (even though we technically didn't need to). While we did check that Sphinx was a high enough version to run, we didn't check that all of the required pip modules were present for Sphinx to be able to render the OMPI docs.

I think it'll be easier to solve this latter problem (i.e., ensure that Sphinx has all the right modules to run) rather than de-tangle the complex make dependencies. Let me look into that.

For the time being, you should be able to configure Open MPI with --disable-sphinx; that should be a good enough workaround.

[jsquyres]

@PhilipDeegan We have the fix committed on main (which should be available in last night's snapshot tarball; if you want to give it a whirl: https://www.open-mpi.org/nightly/main/), and it is queued up for the v5.0.x branch.