[WIP] [ENH] Add section numbers

[nicholst]

This is a WIP to address issue #421, adding section and subsection numbers throughout the document.

Will require extensive checking of a RTD and PDF rendered version to ensure it is doing what it should and doesn't have any bad side effects.

RTD rendering: https://bids-specification.readthedocs.io/en/addsectionnums
PDF rendering: (Find via the ci/circleci "build_docs_pdf" job below, expanded under "show all checks", "artifacts" tab; requires Circle CI login)

Note 1. This takes over from PR #453, which came from a personal branch instead of the main repo.
Note 2. The the content for CSS directly copied and pasted from here: https://stackoverflow.com/questions/48029165/is-there-a-way-to-make-the-headings-sections-and-subsections-numbering-in-markd

[nicholst]

No love on the RTD version... from my browser's developer view, I can see that the css/section_numbering.css file is there and accessible but have no way of knowing if the extra_css action in mkdocs.yml took hold.

@sappelhoff: Where is the PDF version found? From the ci I can see that build_docs_pdf was successful, but then seems to be deleted.

[sappelhoff]

it's here: https://2290-150465237-gh.circle-artifacts.com/0/bids-spec.pdf

you need to:

1. click on "details" of the "build_docs_pdf" job
2. you are now in the circleci webpage of the job
3. find the "artifacts" tab and click on it (if circleci asks you which UI to use, .. I recommend the new one, the artifacts tab is obviously visible there ... they recently updated their UI)
4. find the PDF

edit: Though it says that it finished 5 hours ago 🤷 might be some weird interaction of time zones?

[effigies]

I can see that the css/section_numbering.css file is there and accessible but have no way of knowing if the extra_css action in mkdocs.yml took hold.

It's showing up in the source of the rendered version:

      <link rel="stylesheet" href="css/section_numbering.css">
    
      <link rel="stylesheet" href="https://assets.readthedocs.org/static/css/badge_only.css">
    
      <link rel="stylesheet" href="https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css">
    
      <link rel="stylesheet" href="css/watermark.css">

And following the link finds the CSS file.

It has no effect I can see in Firefox or Chrome.

[nicholst]

Thank you @sappelhoff , @effigies !

Anyway, no love with either the RTD HTML or the PDF.

What's maddening, is that the Markdown Publishing Guide has a PDF rendering with full numbering, but I can find no trace of how that's activated in the associated repo (https://github.com/ironmeld/markdown-publishing-guide). (The number isn't present in the RTD HTML, only the PDF, which is annoying, but still partial success.)

(Same goes for "markdown-guide Documentation" [HTML] [PDF] [Github Repo])

[yarikoptic]

ci/circleci: build_docs artifact — Link to 0/site/01-introduction.html

no longer provides preview so can't quickly check. Although I like section numbers etc, I wonder if that would make it also into "fragment" ids, so e.g. https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/02-magnetoencephalography.html#meg-recording-data would become smth like https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/02-magnetoencephalography.html#4.2.2-meg-recording-data . That would then complicate cross referencing specific section a bit since would start to mandate no new sections introduced inbetween existing ones.

[nicholst]

That is a good point @yarikoptic ... in all the examples I can find the HTML has no numbering so it may not be the case that the links need numbering.

I still think section numbers would make for a more professional spec, but I don't see how I can make it work via the RTD infrastructure.... so I'm happy to declare failure and put this on moth balls (i.e. close this WIP).

[sappelhoff]

@nicholst I am closing this one now. Note that your original proposal from #421 remains open and will contain a link to this "first attempt". So in case anyone wants to pick this up in the future, all previous work is preserved.

Thanks again for giving it a try.

[guiomar]

Hi!! Thanks for all the work done!!
I wonder if anyone had the same problem before. I think this should be a quite common feature to have in a documentation.
I don't really have the technical knowledge, so I don't even know what to google up :) But I also agree with @nicholst that having numbered sections through out the spec and documentation will help to have a clearer general schema overview and will improve navigability.