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

• Fix the main page and include GH-Docu as the main documentation and ExploreASL.org as a secondary one.
• Reorder the mains structure - Tutorials first, reference manual as second
• REQUIREMENTS - Included software doesn't include DCMTK and DCM2NIIX
• First tutorial is Installation
• Second tutorials is Execution
• third tutorial is Import&BIDS - explain also how to run on BIDS alone datasets
• Fourth tutorial is Process + link parameter description
• Fifth tutorial is QC
• 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.
• Sixth tutorial (developer guide) - only there we have functions + full reference of x-struct
• FAQ - give a link to docker and compiled versions.
• Datapartemplate.md goes from code to the manual
• Modules, functions, structural module, xASL-SPM functions - these should all go under a single heading Reference manual!
• Navigation bar with subsections and hiding subsections
• Give and fix studyPar.json example to manual
• Give and fix Fix sourceStructure.json example to manual
• Give dataPar.json example to manual
• Fix ExploreASL dataPar example
• Give studyPar.json template to ExploreASL
• Give sourcestructure.json template to ExploreASL
• About/Contact/etc - our emails, link to GitHub discussions, Google-Forums.
• Change crawler and doc.m scripts
• Configuring dataPar.json for basic examples (missing T1w) - explain this in Processing tutorial
• How to install and configure FSL and how to troubleshoot basic issues with FSL - explain this in Processing tutorial
• How to setup BASIL and when and how to run it. - explain this in Processing tutorial
• Rename templates to source or something in Documentation, change this in Crawler, also remove the CAPS from file-names
• Check that new internal links in manual are working
• Maybe add this somewhere: https://sites.google.com/view/exploreasl/tutorials/how-to-start-exploreasl
• 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

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

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

• the doc functions go into Functions/Developments and get the prefix dev. See also New category of development functions #1073
• 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). Correction Jan: It doesn't deploy, it only copies stuff and creates MD. The real deployment is done using Python.
• 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.