neurolibre/docs.neurolibre.org

Repository containing all the documentation related to neurolibre.

NeuroLibre

This is the website of NeuroLibre, a preprint service for interactive data analysis in neuroscience. The site is rendered at neurolibre.org. You can also check out the NeuroLibre docs.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

⚙️ Development

LiveReload enables the browser to automatically refresh on change during development.

1. Download the LiveReload Chrome plugin
2. Run bundle exec guard

docs.neurolibre.org's Issues

the favicon is hard to see

Would need to be cropped.
It is located here https://github.com/neurolibre/docs.neurolibre.com/blob/master/source/img/logo_neurolibre_small.png

split infrastructures in several pages

Currently the "details on infrastructure" is very long and lacks structure.

There is a chance that this content will form most, if not all, of the content of the docs in the future.

It would be better to refactor the content into smaller, independent sections.

start an editor section

update documentation for reviewers

The following text was drafted when neurolibre was meant to be a stand-alone journal:
https://docs.neurolibre.org/en/latest/REVIEWER.html

It needs to be revised.

First documentation review

https://docs.neurolibre.org/en/latest/

Layout of the documentation

There has been concern in our last meeting about the clarity of this doc (I agree), but without any concrete proposals on how to make it better. We all need to synchronize and agree at least on the layout (not the content) of the doc:

https://docs.google.com/document/d/1tIB9QW8qRoYhsy-4gU0kne2_9oFEnbZOQ8eyz20hfKA/edit?usp=sharing

create docs for readers

currently the section is empty

Update submission docs to note force-execute

I am testing the T1 book freshly generated by roboneuro.
If I use the binder link on the following page, the server starts alright, but none of the cells execute properly
http://neurolibre-data.conp.cloud/book-artifacts/qmrlab/github.com/t1_book/90dc33047e911cc598237621df1e3eebc3207ce0/_build/html/01/IR_DataFitting.html

maintain URLs and meta-data

We are going to need to discuss how we'll deal with maintenance of URLs and meta-data.

This is a part of crossref's requirements.

document "in scope" decision

create a link to the logo archive

and mention the license
https://zenodo.org/record/6836262

document editor invitation

Review: pip resolver note

I accidentally pushed into master without asking for a review.
@mathieuboudreau don't you mind looking at this commit since you are currently facing this issue?

c0c155d

move from alpha to beta

pretty much all the pieces are in place for neurolibre to operate - with the exception of doi minting which can wait for a few months.

So it is time to move the "alpha warning banner" to a "beta warning banner".

User experience feedback (Mathieu)

I'm not done testing the whole process, as it's taking quite a lot of time updating the T1 book to work with the latest version of Jupyter Book (thanks @zelenkastiot!), but I wanted to leave some early feedback. I'll be updated the list by editing this comment.

General UX

• Before Step 1 (or at the very beginning of it), there's missing some kind of high level explanation of what we expect the users will need to do. The 🗂 Preprint repository structure section is the first time that there's something like this explained through the directory structure, and it might confuse some users no knowing how all these folders will be generated or if they all need to be manually created.

By high level, I mean something like:

As a new user, you will need to:

* Create a Jupyter Notebook of your analyses that you want to share.
* Initialize a Jupyter Book template directory (will generate all the files in the *content* folder) and add your Jupyter notebook(s).
* Create files that reproduce your computing environment (files under the *binder* folder)
* Write all relevant bibliography details (paper.md and paper.bib files)

Not necessarily exactly above, but some kind of high-level instructions that will give the new user a birds eye view of the steps they'll need to take would be helpful to understand all the later instructions.

Broken links

• Below second figure, If you would like to submit a NeuroLibre preprint, please read our submission guidelines.
• Markdown link not rendering correctly:

• In Step 1: We suggest testing repo2data locally before you request a RoboNeuro preview service. Instructions are available here.

Text possibly needing to be updated

• Warning: NeuroLibre is at an alpha stage of development, and is not currently open for submissions.
  • Are we still at alpha stage?
• It is tailored for publishing interactive neuroscience notebooks
  • This reads as if we're limiting submissions to neuroscience notebooks, which I don't think is the case. Maybe it could be reworded, listing neuroscience as an example?
• There's an extra paragraph/space after Contributions are welcome, NeuroLibre is fully open-source that I think could be removed.

add DOI link for all references

This is a crossref requirement, and should be part of our author's guide, as well as reviewer check list.

https://www.crossref.org/membership/

Note on submodule remote protocol

I had some unclear error messages with the test build on roboneuro, followed the docs to use CONP binder instance to debug.
The issue turn out to be submodules in my repository.
The remotes of the submodules have to use the HTTPS protocol.
This is a rather niche use case but I thought it might be useful to add in the checklist.

403 Forbidden

The docs (https://docs.neurolibre.com) used to work, but now show a 403 error.

Is this a known/expected behaviour at the moment? I can't recall; did we migrate from org to com or com to org?

document jb debugging

debugging is a long process that should be done directly on our system, and not on user system, This helps alleviate build/execution errors (environment, and hardware).

document meta-review on github

Adding a Quick Start document

The documentation can benefit from having a quick start section. You already have a template repository that you can expand.
Adding "quick start" documentation would make paper submission to the Neurolibre more accessible and less intimidating for non-technical users.

add guidelines for contributing to the project

this project has exemplary guidelines
https://tedana.readthedocs.io/en/latest/

favicon aliasing

When we zoom in into the neurolibre favicon, there is aliasing.
Maybe we could convert the png to vector image like svg ?

_config.yml link does not work

The link for _config.yml documentation in this page does not redirect to the Jupyter Book config documentation. Correct address: https://jupyterbook.org/en/stable/customize/config.html

Point to a minial example repository in the author guideline doc

This is an insight from discussion with @mirhnius at Brianhack Montreal 2023. (Niushia please feel free to chime in.)

For people who has never used binder, the first hurdle is how to make their repository work with binder. Having an minimal example, or point readers to an existing preprint with a simple set up might be a good idea.

Weird things to document

• No svg figures

No more than 5 missing DOI entries, otherwise our limited heroku memory overflows.

document featured.png at the root

Opinion on the new theme

Here is my point of view with the new theme.

These could be some points for discussion :

• The colors for the notes and warnings are quite harsh, I think we should add some transparency. And also add a distinction between the title and content (the old warnings and note are just really great).
• The layout of the doc is not clear. I don't understand how do I navigate from the different pages with the top border. And most of them are dead links so not usefull.
• I think the overall fonts are too small.
• For some sub items, the fonts are larger than the top items (ex https://docs.neurolibre.com/en/latest/INFRASTRUCTURE.html#appendix-a)

Personally I am a real fan of the old new style, but let be open to discussion ;P

What do you think everyone ?

Missinng Jupyter Book version compatibility information

Jupyter Book has a (very annoying) habit of completely rehauling their project frequently, and so I think it'd be essential to know in the docs 1 - for what version of Jupyter Book these instructions were written for, and 2- what versions do we support on NeuroLibre.

For example, I'm trying to test our T1 book example which is a couple of years old in the submission process, but there appears to be a lot of files missing (eg toc) and differences in folder structres, and it's not clear to me if there's an easy workaround for this or if I'll have to restart the project from scratch using the latest Jupyter Book (which is missing some discontinued features that we were using in the original Jupyter Book that I compiled our T1 Book with)

document "start metareview"

This is for EiC

document data limits

and encourage pulling from stable sources (inc DOIs).

document wall time

The total limit is 1h (and 10 retries). See this code

This time includes repo2data + jb build.
jb build itself is equal to notebook execution + html build.

There is no wall time on notebook execution, but everything needs to complete within 1 hour.
If the submission uses caching, build will be retried up to 10 times.
It is because the build may fail due to repo2data, however the results of repo2data get cached so the build may complete after restarting from the cache.

build error on readthedocs

ERROR: Could not find a version that satisfies the requirement sphinx_bootstap_theme (from -r requirements.txt (line 3)) (from versions: none)
ERROR: No matching distribution found for sphinx_bootstap_theme (from -r requirements.txt (line 3))

update reviewer documentation

just a placeholder for now. This issue is anticipated to turn into a thread, spawning issues to improve reviewer docs.

color palette of the logo

The red logo does not work with the readthedocs theme.

For the main website, we should stick to the CONP red.

But for the docs, I think it would make sense to have a different palette.
Have the book in white, get rid of the current white outline, and turn the neuron into black would be sober and nice, I think.

The corresponding file is located here:
https://github.com/neurolibre/docs.neurolibre.com/blob/master/source/img/logo_neurolibre.png