rfc13: use function directive to make PMI API docs more readable

[garlick]

Just a bit of cleanup in RFC 13 which I had been referring to lately. Now the PMI function defintions look more like Jansson's API docs!

[grondo]

The github workflow config needs an update, might as well throw it in here?

commit c880d810f015e0ab01e0fc37b26181fcfcd41020
Author: Mark A. Grondona <mark.grondona@gmail.com>
Date:   Wed Dec 14 18:42:24 2022 -0800

    ci: update python and checkout actions

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index e351089..a2e607d 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -5,7 +5,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request'
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         ref: ${{ github.event.pull_request.head.sha }}
         fetch-depth: 0
@@ -16,12 +16,12 @@ jobs:
     name: make check
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         ref: ${{ github.event.pull_request.head.sha }}
-    - uses: actions/setup-python@v1
+    - uses: actions/setup-python@v4
       with:
-        python-version: 3.6
+        python-version: '3.9'
     - name: install dependencies
       run: |
         pip3 install --upgrade -r ./requirements.txt
@@ -33,12 +33,12 @@ jobs:
     name: make linkcheck
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
       with:
         ref: ${{ github.event.pull_request.head.sha }}
-    - uses: actions/setup-python@v1
+    - uses: actions/setup-python@v4
       with:
-        python-version: 3.6
+        python-version: '3.9'
     - name: install dependencies
       run: |
         pip3 install --upgrade -r ./requirements.txt                                                                                  

Maybe try that?

[grondo]

Great! Looks nice! I noticed a strangeness in the sections listed along the sidebar, but my guess is that this was already a problem;

[grondo]

Nice! LGTM.

[vsoch]

The nesting in the sidbar TOC is usually controlled where the menu is defined, e.g.,

.. toctree::
   :caption: Getting started
   :name: getting_started
   :hidden:
   :maxdepth: 2

So if possible, if there's nothing else at that level, you could nix it. (maxdepth -1). If there is, you'd probably need another trick: https://stackoverflow.com/questions/15035546/hide-sphinx-subsections-from-main-toctree.

Also, has there been feedback about the style of the docs? I personally find the default readthedocs template hard to move around, or kind of depressing if/when I see it that nobody changed anything. One thing I wanted to bring up for discussion is that maybe part of users being better able to find things and better enjoy / contribute to the docs overall would be to reformat into a nicer template? Here are some randoms that I've done that all use sphinx (and I even use markdown for a few for easier user contribution!)

• https://oras-project.github.io/oras-py/getting_started/user-guide.html#creating-oci-objects (sphinx mkdocs markdown)
• https://singularity-hpc.readthedocs.io/en/latest/ (sphinx, rst, with branding)
• https://pydicom.github.io/pydicom/stable/ (sphinx, rst, with branding and added gallery modules)

I think we have an opportunity moving forward to really make the docs shine, and part of that, although it's not "cool work" is branding. E.g., this page https://flux-framework.org/ to any trained eye is a GitHub pages theme called Cayman https://pages-themes.github.io/cayman/ with maybe a color changed. And I'm not saying we have to go this route, but now we have two flux associated projects with these docs:

• https://flux-framework.org/flux-operator/
• https://flux-framework.org/flux-restful-api/auto_examples/index.html

If the team wants to chat about these ideas, and if there is a desire to have a nice, unified portal for flux projects (e.g., akin to https://software.llnl.gov/radiuss/projects/ but for fewer projects and rebranded for flux) and then more unified branding of the individual project docs, I could probably help. It will make a difference, I think, when new users are trying it out and forming impressions, and/or finding/not finding stuff easily (re: the email earlier today). Let me know what you think!

[vsoch]

And to express some of my criticism of the default template, even on a small screen there is like, a swimming pool sized block of unused space on the right:

Oh look, someone is having a pool party! 🐩

But even a small change of template design all of a sudden opens up the docs and uses that space for text, graphics, tutorials, and often moving the page navigation to the right and main on the left, to have both without having to choose one. And the docs are more open and easy on the eyes in not requiring more content shoved into a smaller space.

[garlick]

Thanks @vsoch - I made several attempts with the toctree directives and, getting nowhere, decided that it was probably a misstep to put headings under function defs that are not themselves headings, so I just dropped that commit from this PR.

Regarding the feedback on the overall docs format, what you're saying makes sense and when someone has some time I agree that we could use a makeover and some consistent branding. I'll transfer your comments into an issue in the flux-docs repo so we can track this.

[garlick]

Thanks for the approval @grondo - I'll set MWP.
Edit: and for the CI fix!