Update documentation functions to a new structure

jan-petr commented 2 years ago

Description

We will change slightly the structure of the Documentation and we need to update the docu scripts and also some internal descriptions.

Note that we are updating some of these functions already for 1.9.0. Those edits, we will edit both in ExploreASL-code and directly in the documentation by hand so that we don't have to re-run the crawler. The docucrawler and automatic generation should be used only from version 1.9.0 and further

Tasks

[x] Fix the main page and include GH-Docu as the main documentation and ExploreASL.org as a secondary one.
[x] Reorder the mains structure - Tutorials first, reference manual as second
[x] REQUIREMENTS - Included software doesn't include DCMTK and DCM2NIIX
[x] First tutorial is Installation
[x] Second tutorials is Execution
[x] third tutorial is Import&BIDS - explain also how to run on BIDS alone datasets
[x] Fourth tutorial is Process + link parameter description
[x] Fifth tutorial is QC
[x] Split dataParTemplate/Processing/Developer guide. Advanced goes to developer. All user stays in dataPar, examples go to processing. But remove as much as possible unused ones from Processing.
[x] Sixth tutorial (developer guide) - only there we have functions + full reference of x-struct
[x] FAQ - give a link to docker and compiled versions.
[x] Datapartemplate.md goes from code to the manual
[x] Modules, functions, structural module, xASL-SPM functions - these should all go under a single heading Reference manual!
[x] Navigation bar with subsections and hiding subsections
[x] Give and fix studyPar.json example to manual
[x] Give and fix Fix sourceStructure.json example to manual
[x] Give dataPar.json example to manual
[x] Fix ExploreASL dataPar example
[x] Give studyPar.json template to ExploreASL
[x] Give sourcestructure.json template to ExploreASL
[x] About/Contact/etc - our emails, link to GitHub discussions, Google-Forums.
[x] Change crawler and doc.m scripts
[x] Configuring dataPar.json for basic examples (missing T1w) - explain this in Processing tutorial
[x] How to install and configure FSL and how to troubleshoot basic issues with FSL - explain this in Processing tutorial
[x] How to setup BASIL and when and how to run it. - explain this in Processing tutorial
[x] Rename templates to source or something in Documentation, change this in Crawler, also remove the CAPS from file-names
[x] Check that new internal links in manual are working
[x] Maybe add this somewhere: https://sites.google.com/view/exploreasl/tutorials/how-to-start-exploreasl
[x] I recommend adding a Tutorials (data preparation) step which contains explanations about the different foldernames in BIDS and what they should contain, only brief explanations and links to the BIDS website. @BeatrizPadrela already has something perfect for this in the ExploreASL website. We can then also provide the testdataset option in ExploreASL to check processing and as an example.

Specific things to be checked - it is easy to understand how to

[x] Download and run the basic version
[x] Run a simple example with ASL-BIDS without additional parameters
[x] Run an example that has to be configured (through dataPar.json) that the T1w is missing
[x] It is explained how to install FSL
[x] It is explained how to run BASIL, when that is needed, that it needs FSL then and how to setup FSL in that case
[x] Troubleshooting with missing FSL directory
[x] Check that links in manual are working

Things to be added to the doc-Crawler and docInitialize:

[x] the doc functions go into Functions/Developments and get the prefix dev. See also #1073
[x] the automatic crawling is separated from the parts that can be manually adjusted (currently called "templates") separate these from the deployment
[x] correct the naming of the functions (the DocCrawler does more than only crawling the docs, the "initialization" not only initializes (i.e., just readying stuff for deployment) but actually deploys). Correction Jan: It doesn't deploy, it only copies stuff and creates MD. The real deployment is done using Python.
[x] improve the comments and function headers, by adding the sections (0. Admin 1. Crawling 2. Manual copying etc) inside the functions

Release notes

Improve and restructure documentation.

HenkMutsaerts commented 2 years ago

@jan-petr: This is what I had noted to improve xASL_dev_DocCrawler:

the doc functions go into Functions/Developments and get the prefix dev
the automatic crawling is separated from the parts that can be manually adjusted (currently called "templates")
separate these from the deployment
correct the naming of the functions (the DocCrawler does more than only crawling the docs, the "initialization" not only initializes (i.e., just readying stuff for deployment) but actually deploys)
improve the comments and function headers, by adding the sections (0. Admin 1. Crawling 2. Manual copying etc) inside the functions

jan-petr commented 2 years ago

Yes - I have added all those above. Documentation is now improved. We will check if the new Documentation looks good. And I will do these functions for creation later - as these affect the process of creation but not how the documentation later looks. So this doesn't need to be checked by everybody.

BeatrizPadrela commented 2 years ago

Specific things to be checked - it is easy to understand how to

[x] Download and run the basic version -> Maybe add this somewhere: https://sites.google.com/view/exploreasl/tutorials/how-to-start-exploreasl
[x] Run a simple example with ASL-BIDS without additional parameters
[x] Run an example that has to be configured (through dataPar.json) that the T1w is missing -> It's clear that one just needs to use {"x":{"modules":{"asl":{"bUseMNIasDummyStructural":1}}}} in the dataPar
[x] It is explained how to install FSL -> This is just through the link that goes to the FSLInstallation page, right?
[x] It is explained how to run BASIL, when that is needed, that it needs FSL then and how to setup FSL in that case

-> Yes and yes

[x] Troubleshooting with missing FSL directory
[x] Check that links in manual are working ->These links do not work:

MDijsselhof commented 2 years ago

Specific things to be checked - it is easy to understand how to

[x] Download and run the basic version
- Maybe mention a BIDS compatible dataset is required and provide the option to the testdataset in ExploreASL to check if everything is ready to go.
[x] Run a simple example with ASL-BIDS without additional parameters
- Maybe explain why we first initialise, to make sure all required functions and folders are added to the working directory.
[x] Run an example that has to be configured (through dataPar.json) that the T1w is missing
- Maybe again provide the location and purpose of the dataPar.json in Tutorials (Processing)
- maybe add 'A template datapar.json can be found in the ExploreASL/templates directory' at the beginning of the tutorial and 'For a complete overview of all processing options, see the dataParTemplate.md' at the end.
[x] It is explained how to install FSL
[x] It is explained how to run BASIL, when that is needed, that it needs FSL then and how to setup FSL in that case
- It is clear, but only for multi-PLD and time-encoded. The option to process single-PLD data is not described anywhere as far as I can tell.
[x] Troubleshooting with missing FSL directory
[x] Check that links in manual are working Link that do not work:

I recommend adding a Tutorials (data preparation) step which contains explanations about the different foldernames in BIDS and what they should contain, only brief explanations and links to the BIDS website. @BeatrizPadrela already has something perfect for this in the ExploreASL website. We can then also provide the testdataset option in ExploreASL to check processing and as an example.

jan-petr commented 2 years ago

All comments taken into account - remains to merge one Tutorial from ExploreASL.org and to update the Docu-Crawler functions.

ExploreASL / ExploreASL