Beautification of rst documentation

[zerothi]

Listified the elements and ensured links were
properly set.

This will close #11340 (eventually)

Signed-off-by: Nick Papior nickpapior@gmail.com

[ompiteam-bot]

Can one of the admins verify this patch?

[jsquyres]

I think you can squash the 2nd commit into the 1st commit.

[jsquyres]

In list-ifying all the See Also's, I don't think I have a strong opinion, but I do have an opinion. 😄

We took our cue from other Linux and MacOS man pages on how to do the See Also's. For example, man ls in MacOS 13.1:

And if I man uptime on Ubuntu 22.04:

Meaning: if we want to keep with conventions of other man pages, we should probably add commas to our list of man pages, not bullets.

[zerothi]

I partially agree ;)

The man-page comma-separated links might be good for a terminal view, but definitely not for a HTML page view. The links gets bunched together. I think this should be fixed via some other means, e.g. by some customization of the conf.py file. I'll have a look whether this could be done.

[zerothi]

I am thinking about changing the error block to something like this:

would this be an acceptable change?
The specific change involves compressing the two lists into 1 list to show their coherence. My argument would mainly be to reduce the length of the ERROR section.

[zerothi]

@jsquyres I believe a first merge would be appropriate?
Only need feedback not he ERROR change I proposed?

[jsquyres]

I'm good with your ERRORS change/combination of 2 lists.

You have a minor RST error that CI found:

/home/ubuntu/workspace/pen-mpi.pull_request-v2_PR-11367/docs/man-openmpi/man3/MPI_Pack.3.rst:93: WARNING: Could not lex literal_block as "c". Highlighting skipped.

[zerothi]

I'm good with your ERRORS change/combination of 2 lists.

You have a minor RST error that CI found:

/home/ubuntu/workspace/pen-mpi.pull_request-v2_PR-11367/docs/man-openmpi/man3/MPI_Pack.3.rst:93: WARNING: Could not lex literal_block as "c". Highlighting skipped.

I'll check!

[zerothi]

I didn't get why the MPI_Pack was doing erroneous things, lets see if this small amendment fixes it.
I looked at https://readthedocs.org/api/v2/build/19354327.txt and couldn't find the warning you mentioned?

[jsquyres]

I didn't get why the MPI_Pack was doing erroneous things, lets see if this small amendment fixes it. I looked at https://readthedocs.org/api/v2/build/19354327.txt and couldn't find the warning you mentioned?

It was in https://jenkins.open-mpi.org/jenkins/job/open-mpi.pull_request-v2/job/PR-11367/7/console -- one of the other CI tests (I think it was the make dist test on the overall continuous-integration/jenkins/pr-head CI test). It takes (much) longer than the RTD CI -- the red "X" showed up much later than the RTD CI test green checkmark.

[jsquyres]

I tweaked / fixed some other typos in the example in the MPI_Pack.3.rst commit.

[zerothi]

I have tried to figure out the man-page stuff... But I must admit the documentation for sphinx/docutils is not wrapping my head...

I think this will deserve a second go later.

Here would be a base-plan on how to use it:

This should just be placed at the bottom of the conf.py file, and then one would be able to do

Please read the documentation about :man3:`MPI_Init` ...

Here:

def man_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    """ This does not work yet!

    A work in progress, this is mainly to indicate what we intent to do
    for man-page references.

    Adding multiple arguments to inline roles in Sphinx is not ideal.

    Instead it would be better to have roles as:

    :man3:`MPI_Init`

    which would result in MPI_Init(3) in the man-page, but a regular
    link in the web-page.

    It should be able to handle:
   
    :man3:`custom title <MPI_Init>` and result in custom title (omitting (3)).
    """
    
    # The man<> name can get the number
    n = name[3]

    if '<' in text:
        # there must be a space:
        #  :manX:`MPI_toahe <MPI_Init>`
        ref_text, link = text.split("<", 1)
        ref_text = ref_text[:-1] # remove end space
        link = link[:-1] # remove end >
    else:
        ref_text = f"{text}({n})"
        link = text

    # lower-case the link
    link = link.lower()

    raise NotImplementedError(f"still no :{name}: role... please hold!")


def setup(app):
    app.add_role("man1", man_role)
    app.add_role("man3", man_role)
    app.add_role("man5", man_role)

[jsquyres]

@zerothi Now that this has merged on main, can you make a cherry-pick PR to bring all of these commits to the v5.0.x branch? See the bits about cherry picking in https://docs.open-mpi.org/en/v5.0.x/developers/git-github.html#git-branch-scheme.

[jsquyres]

When you cherry-pick these commits to v5.0.x, please include 3515978, which fixes a problem that showed up in our nightly testing (not sure why it didn't show in the PR CI).

[zerothi]

I'll have a look end of this week!