Consolidate NMODL docs and improve their discoverability

[kbvw]

Duplicate versions of the NMODL documentation pages currently exist under Python and HOC:

hoc/modelspec/programmatic/mechanisms/nmodl.html
hoc/modelspec/programmatic/mechanisms/nmodl2.html
python/modelspec/programmatic/mechanisms/nmodl.html
python/modelspec/programmatic/mechanisms/nmodl2.html

Very little content in these pages is specific to either HOC or Python, and the pages have diverged, with recent additions only added to the Python versions, and some earlier corrections only added to the HOC versions.

In addition, these pages are nearly impossible to find by clicking through the documentation, even though they serve as a main source of documentation for the NMODLanguage.

This PR merges the Python/HOC versions of these pages together and moves them to the following location:

nmodl/language/nmodl.html
nmodl/language/nmodl_neuron_extension.html

The (nearly empty) page previously at this location is renamed to nmodl/tutorials.html.

[kbvw]

A few more possible improvements pending discussion:

• The POINTER section exists both in nmodl.html and nmodl_neuron_extension.html (previously nmodl2.html). Presumable this section can be removed in the former page, as it concerns the NEURON block?
• For the few sections that have Python/HOC-specific content (notably the above-mentioned POINTER section), the current solution states the examples after the other. This looks a bit messy and could be improved with language-specific tabs, if it is okay to add the sphinx-inline-tabs dependency. (Example: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/.)
• The tutorials page (previously the only page under the NMODLanguage tab) seems to be a messy draft consisting mostly of placeholders. I am hesitant about removing a page outright, but presumably it could be removed, and perhaps reintroduced in a better state later.

Many more things can be cleaned up about these pages, but discoverability and preventing the duplicates from diverging more would seem to be the priority.

[azure-pipelines]

✔️ a6df245 -> Azure artifacts URL

[azure-pipelines]

✔️ fefd2df -> Azure artifacts URL

[JCGoran]

• The POINTER section exists both in nmodl.html and nmodl_neuron_extension.html (previously nmodl2.html). Presumable this section can be removed in the former page, as it concerns the NEURON block?

Briefly skimming the source, I'd say yes, POINTER should be part of the NEURON block (and nrnivmodl errors out if you try putting it anywhere else), but just to be sure I'll let @ramcdougal and @nrnhines chime in.

• For the few sections that have Python/HOC-specific content (notably the above-mentioned POINTER section), the current solution states the examples after the other. This looks a bit messy and could be improved with language-specific tabs, if it is okay to add the sphinx-inline-tabs dependency. (Example: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/.)

If it'd improve readability, doesn't require too many changes, and doesn't have any conflicts with existing packages, I'm all for it!

• The tutorials page (previously the only page under the NMODLanguage tab) seems to be a messy draft consisting mostly of placeholders. I am hesitant about removing a page outright, but presumably it could be removed, and perhaps reintroduced in a better state later.

I would be in favor of keeping it, but updating the links (see this page, links at the top need to be changed), and maybe putting a giant warning sign "UNDER CONSTRUCTION/DEVELOPMENT" for now, we can remove/modify it in another PR.

[kbvw]

Thanks for the comments Goran!

For the turorials page, people in the meeting yesterday seemed to be in favour of removing it for now and adding it back later if there's time to work it out.

I'm now implementing the tabs so we can see how that looks, will push it later today.

[nrnhines]

• The POINTER section exists both in nmodl.html and nmodl_neuron_extension.html (previously nmodl2.html). Presumable this section can be removed in the former page, as it concerns the NEURON block?

Briefly skimming the source, I'd say yes, POINTER should be part of the NEURON block (and nrnivmodl errors out if you try putting it anywhere else), but just to be sure I'll let @ramcdougal and @nrnhines chime in.

I agree.

• For the few sections that have Python/HOC-specific content (notably the above-mentioned POINTER section), the current solution states the examples after the other. This looks a bit messy and could be improved with language-specific tabs, if it is okay to add the sphinx-inline-tabs dependency. (Example: https://packaging.python.org/en/latest/guides/writing-pyproject-toml/.)

If it'd improve readability, doesn't require too many changes, and doesn't have any conflicts with existing packages, I'm all for it!

I agree

• The tutorials page (previously the only page under the NMODLanguage tab) seems to be a messy draft consisting mostly of placeholders. I am hesitant about removing a page outright, but presumably it could be removed, and perhaps reintroduced in a better state later.

I would be in favor of keeping it, but updating the links (see this page, links at the top need to be changed), and maybe putting a giant warning sign "UNDER CONSTRUCTION/DEVELOPMENT" for now, we can remove/modify it in another PR.

I lean toward (temporary?) removal. The negative impression at the moment is pretty strong. Is it much help to a future documentation author?

[JCGoran]

Is it much help to a future documentation author?

The only thing that could be potentially helpful are the example mod files, which are sorely missing from the main docs (though admittedly the examples are also very sparsely documented), and having them in the docs somewhere as a future reference could be useful (rather than having to write them from scratch or digging them out from git history). Again, I've no strong opinion on this.

[nrnhines]

Very nice improvement. Forms a good basis for bringing some details up to date.

[azure-pipelines]

✔️ 7706c51 -> Azure artifacts URL

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[azure-pipelines]

✔️ 3d60327 -> Azure artifacts URL

[kbvw]

Thanks Goran and Michael for the comments!

• The duplicate POINTER/Pointer Communication sections are now merged and only the latter is included, under nmodl_neuron_extension.html.
• The same Pointer Communication section (and a few others like PROCEDURE in nmodl.html) now have synchronized mini tabs for Python/HOC syntax

The only thing that could be potentially helpful are the example mod files, which are sorely missing from the main docs (though admittedly the examples are also very sparsely documented), and having them in the docs somewhere as a future reference could be useful (rather than having to write them from scratch or digging them out from git history). Again, I've no strong opinion on this.

Regarding the tutorial page, I removed the small .rst file that simply included the notebook, and it's entry from the index. And then I kept the .ipynb notebook with the contents. (Admittedly also because, being the only notebook in the repo, removing it seemed to break some notebook-related CI.) So now it's invisible, but still around if someone wants to flesh it out and include it again.

[bbpbuildbot]

Logfiles from GitLab pipeline #218225 (:no_entry:) have been uploaded here!

Status and direct links:

• ✅ mac_m1_cmake_build: [cmake, ON, OFF, OFF, address]
• ✅ spack_setup
• ✅ build:nmodl
• ✅ build:neuron:nmodl:intel:legacy
• ✅ build:neuron:nmodl:intel:shared
• ✅ build:neuron:nmodl:nvhpc:acc:legacy
• ✅ build:neuron:nmodl:nvhpc:acc:shared
• ✅ build:neuron:nmodl:nvhpc:omp:legacy
• ✅ build:neuron:nmodl:nvhpc:omp
• ✅ test:neuron:nmodl:intel:legacy
• ✅ test:neuron:nmodl:intel:shared
• ✅ test:neuron:nmodl:nvhpc:acc:legacy
• ✅ test:neuron:nmodl:nvhpc:acc:shared
• ✅ test:neuron:nmodl:nvhpc:omp:legacy
• ✅ test:neuron:nmodl:nvhpc:omp