search

neuronsimulator / nrn

NEURON Simulator
http://nrn.readthedocs.io
Other
376 stars 113 forks source link

Consolidate NMODL docs and improve their discoverability #2922

Closed kbvw closed 1 week ago

kbvw commented 2 weeks ago

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 commented 2 weeks ago

A few more possible improvements pending discussion:

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[bot] commented 2 weeks ago

✔️ a6df245d30e63a91d06771dcca460027f7533185 -> Azure artifacts URL

bbpbuildbot commented 2 weeks ago

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

Status and direct links:

azure-pipelines[bot] commented 2 weeks ago

✔️ fefd2df8a931715a80b9e388a588181c76fef6e0 -> Azure artifacts URL

bbpbuildbot commented 2 weeks ago

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

Status and direct links:

JCGoran commented 2 weeks ago
  • 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 commented 2 weeks ago

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 commented 2 weeks ago
  • 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 commented 2 weeks ago

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.

azure-pipelines[bot] commented 2 weeks ago

✔️ 7706c51ff6c2379be4db178f7db9d13b93b27d39 -> Azure artifacts URL

bbpbuildbot commented 2 weeks ago

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

Status and direct links:

sonarcloud[bot] commented 2 weeks ago

Quality Gate Passed 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[bot] commented 2 weeks ago

✔️ 3d60327ce062efcd41e4ea85a50d6d71019ce528 -> Azure artifacts URL

kbvw commented 2 weeks ago

Thanks Goran and Michael for the comments!

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 commented 2 weeks ago

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

Status and direct links: