Refactorization and reorganization (#67)

* renaming walkthrough_ files and updating the corresponding links

* fixing typos in about and minor update in content

* changing page title in administrors

* changing page title in administrors

* typo and title in annotation

* minor fix

* updating gitignore

* minor fix in contribute

* fixing typos, adding some todo-ed links (some remain)

* retitling export

* removed main title in FAQ

* minor fix in import.md

* more content in the index page

* changing title in search and predict

* retitling segment
and adding credits to flochiff

* retitling train

* adding link to script's issue for known bug in import

* moving getting a model from transcribe to predict
and fixing some phrasing along the way
plus adding a illustration of the panels

* addng a stock_images folder for illustration that could be useful later

* adding a preamble in segment

* add shortcuts for panels in transcribe

* retitling users.md and solving a couple of todos

* minor fixes in virtual keyboard section + typos

* editing the walkthrough page

* leaving a todo in walkthrough

* fixing home page

* minor change in the side bar

* more info in the API page

* final wrap up

* fixing errors spotted by FC

.gitignore

@@ -155,4 +155,5 @@ cython_debug/
 
 # End of https://www.toptal.com/developers/gitignore/api/python,jupyternotebooks
 
-site/
+site/
+.vscode/

docs/FAQ.md

@@ -6,9 +6,7 @@ authors:
 date: 2023-02-22
 ---
 
-# Frequently asked questions about eScriptorium
-
-???+ Tip "Missing answers!"
+!!! Tip
     Feeling like we missed an important question? See how to [contribute](contribute.md) to this tutorial and submit your idea!
 
 [TOC]
@@ -63,7 +61,7 @@ If you use a [local deployment](https://gitlab.com/scripta/escriptorium/-/wikis/
 
 eScriptorium is a decentralized software, which means that there are as many databases as there are instances of eScriptorium. It is impossible to synchronize two instances, unless they share the same database, which is unlikely.
 
-You can, however, update the content of your projects and documents from one instance to another with the help of the [export](walkthrough_export.md) and [import](walkthrough_import.md) features. For this, you need to have an account on both the source and the target instances.
+You can, however, update the content of your projects and documents from one instance to another with the help of the [export](export.md) and [import](import.md) features. For this, you need to have an account on both the source and the target instances.
 
 ## Who can I contact to request a new feature or signal a bug?
 
@@ -95,4 +93,4 @@ Onboarding is a mini tutorial explaining the basics of eScriptorium to new users
 Any user can reset onboarding by going into their profile and clicking "Reset onboarding".
 
 !!! Tip "More info"  
-     For more information on the Profile page, see [user-related features](walkthrough_users.md)
+     For more information on the Profile page, see [user-related features](users.md)

docs/about.md

@@ -1,13 +1,17 @@
 ---
-title: About the eScriptorium Tutorial
+title: About the eScriptorium documentation
 summary: About the context of creation of this documentation.
 authors:
     - Alix Chagué
-date: 2023-02-21
+date: 2023-04-21
 ---
 
-# About the eScriptorium Tutorial
+# About this eScriptorium documentation
 
-This webite was created with the intention to provide the community with a useful platform to share a clear and up-to-date documentation on [SCRIPTA](https://scripta.psl.eu/)'s eScriptorium application.
+This website was created with the intention to provide the community with a useful platform to share a clear and up-to-date documentation on [SCRIPTA](https://scripta.psl.eu/)'s eScriptorium application.
 
-This documentation is not run by SCRIPTA and is instead created by the community of eScriptorium users, for the community.  
+This documentation is not run by [SCRIPTA](https://scripta.psl.eu/) and is instead created by the community of eScriptorium users, for the community.  
+
+If you want to know more about eScriptorium and its context of creation, you can read the [FAQ](FAQ.md) or go to [SCRIPTA](https://scripta.psl.eu/)'s website.
+
+If you want to contribute to the discussions around this documentation, see "[How to contribute](contribute.md)"!

docs/walkthrough_administrators.md → docs/administrators.md

@@ -1,12 +1,12 @@
 ---
-title: eScriptorium's administration
-summary: About the back end of eScriptorium.
+title: Administration of eScriptorium
+summary: About the back end of eScriptorium and other administrator-related features.
 authors:
     - Alix Chagué
 date: 2023-01-31
 ---
 
-# Walkthrough :  eScriptorium's administration
+# Administration of eScriptorium
 
 ## Back-end
 
@@ -26,10 +26,10 @@ The page displays information on CPU, GPU and Disk usage from the users of the a
 
 ## Task monitoring and task reports
 
-!!! Warning 
+!!! Warning  
     The documentation on these features is not complete.
 
-See in [User-related features](walkthrough_users.md):
+See in [User-related features](users.md):
 
-- [Task reports](walkthrough_users.md#task-reports)
-- [Task monitoring](walkthrough_users.md#task-monitoring)
+- [Task reports](users.md#task-reports)
+- [Task monitoring](users.md#task-monitoring)

docs/walkthrough_annotate.md → docs/annotate.md

@@ -1,14 +1,14 @@
 ---
-title: Annotate with eScriptorium
+title: Annotation in eScriptorium
 summary: About the annotation features in eScriptorium.
 authors:
     - Alix Chagué
-date: 2023-02-22
+date: 2023-04-21
 ---
 
-# Walkthrough: annotation with eScriptorium
+# Annotation in eScriptorium
 
-???+ Warning
+!!! Note
     This section details the "Annotation" components, not the "Segmentation" features, which are two different things.
 
 Annotation can be performed at two levels:  
@@ -59,7 +59,7 @@ To draw an annotation on an image, go to the "Edit" page and activate the "Sourc
 
 To remove an annotation from the image, click on it and press the trash-can icon. It is also possible to press ++delete++ after selecting the annotation.
 
-![image: illustration of the process to reove an annotation from an image](img/annotate/remove_image_annotation.gif "Remove an annotation by pressing the trash-can button or the delete key")
+![image: illustration of the process to remove an annotation from an image](img/annotate/remove_image_annotation.gif "Remove an annotation by pressing the trash-can button or the delete key")
 
 ### Delete a category for image annotation
 

docs/api.md

@@ -0,0 +1,18 @@
+---
+title: eScriptorium's API
+summary: About the API of eScriptorium.
+authors:
+    - Alix Chagué
+date: 2023-04-21
+---
+
+# eScriptorium's API
+
+!!! Note
+    An API (for Application Programming Interface) is an interface that allows a program to interact with the application without using human actions on the graphic interface.
+
+eScriptorium has an RESTful API endpoint accessible at `{base_url}/api/`.  
+
+> For example : `escriptorium.example/api`.
+
+You can use the escriptorium-connector Python library to interact with the application's API. You can find more information about it here: https://pypi.org/project/escriptorium-connector/

docs/walkthrough_collaborate.md → docs/collaborate.md

@@ -6,15 +6,15 @@ authors:
 date: 2023-02-24
 ---
 
-# Walkthrough: collaborate within eScriptorium
+# Collaborate within eScriptorium
 
 eScriptorium allows collaboration between users of the same instance with features such as teams and sharing.
 
 ## Teams
 
 Users can be grouped inside a team. The main purpose of teams is to facilitate [sharing documents or projects](#share-a-project-or-a-document). Teams are also helpful to identify a group of people working on the same project or coming from the same institution. Users can be part of several teams at a time.  
 
-It is possible to manage teams from the [Profile page](walkthrough_users.md#review-and-edit-your-profile). Team management includes:  
+It is possible to manage teams from the [Profile page](users.md#review-and-edit-your-profile). Team management includes:  
 
 - Creating a team,  
 - Leaving a team,  
@@ -23,17 +23,17 @@ It is possible to manage teams from the [Profile page](walkthrough_users.md#revi
 
 Only the owner of a team is allowed to add or remove members or to transfer ownership. The owner of a team cannot leave it without first transferring the ownership to another user.
 
-??? Note "No deleting, no renaming"
+!!! Note "No deleting, no renaming"
     It is currently impossible to delete a team or to rename a team.
 
-??? Note "One owner per team"
+!!! Note "One owner per team"
     There can only be one owner at a time.
 
 ## Invite a user
 
 In eScriptorium, some users can have the right to invite new users. The invitation rights are not activated for everyone.
 
-You can find more information about inviting new users in the [user-related features walkthrough](walkthrough_users.md#invite) section.
+You can find more information about inviting new users in the [user-related features walkthrough](users.md#invite) section.
 
 ## Share a project or a document
 
@@ -53,7 +53,6 @@ Then you can click on the "Share" button, a green pop-up message will then be di
 !!! Note
     If you enter an incorrect username, the application will still consider that sharing was successful and will then displayed the green pop-up message. One way to make sure the project is actually shared to the user you want is to click again on "Share this project" and check that they appear in the list of Users, with the box checked.
 
-
 ### Share a document
 
 Go to a document you own and that you want to share, and then click on the "Description" tab. You can then click on the "Share this document" button, and the same pop-up box used for sharing a project will open.
@@ -78,7 +77,6 @@ Choose a user or a team from either one of the two dropdown menus, and click on
 
 All users or teams you shared the model with are also listed here. Users will have the `User` type, and teams the `Group` type. You also have the name of the user or the team, and the full name or identifier.
 
-
 !!! Note
     You can only share a model that you own.
 

docs/contribute.md

@@ -25,5 +25,5 @@ Before opening a ticket, make sure that it is not already handled by another iss
 
 If you want to help us with already identified problems, you can also browse the [issues tagged with "help wanted"](https://github.com/alix-tz/escriptorium-tutorial/labels/help%20wanted).
 
-!!! note
+!!! Note
     When you contribute, feel free to add your name to the list of authors in the page's metadata!

docs/walkthrough_export.md → docs/export.md

@@ -1,16 +1,16 @@
 ---
-title: Exporting models and annotations from eScriptorium
+title: Exporting data from eScriptorium
 summary: Tutorial on export features in eScriptorium.
 authors:
     - Hugo Scheithauer, Alix Chagué, Floriane Chiffoleau
 date: 2023-02-13
 ---
 
-# Walkthrough: Export from eScriptorium
+# Export data from eScriptorium
 
 ## Export transcription and segmentation models
 
-eScriptorium allows users to export models that were previously imported, or models they trained. 
+eScriptorium allows users to export models that were previously imported, or models they trained.
 
 To do so, go to the "My Models" page, accessible via the navigation bar, in the upper right section of the interface, or via `{base_url}/models/`.
 
@@ -19,7 +19,7 @@ All models linked to a specific account are listed there with their metadata.
 You can export a model with the download button, located after all its metadata on the right. It will then download a file with the `.mlmodel` extension.
 
 !!! Note
-    A model will either have the `Segment` role if it is a segmentation model, or the `Recognize` role if it is a transcription model.  <!-- todo: add link to train -->
+    A model will either have the `Segment` role if it is a segmentation model, or the `Recognize` role if it is a transcription model. See the [train](train.md) section for more details.
 
 ![Image: Illustration of the download button for downloading transcription and segmenting models.](img/export/escriptorium_export_model.png "Downloading a model with the download button.")
 
@@ -42,8 +42,8 @@ In the first drop-down menu, you can select which transcription version is to be
 
 !!! Note
     - Manual transcriptions are registered as the **manual** version.
-    - Imported transcriptions, when batch imported with a zip file, are registered as the **Zip import** version by default. You can name a transcription version during import. <!-- todo: add link to import -->
-    - Transcriptions predicted with a model are named after the model. <!-- todo: add link to predict transcription -->
+    - Imported transcriptions, when batch imported with a zip file, are registered as the **Zip import** version by default. You can name a transcription version during [import](import.md#import-segmentation-and-transcription).
+    - Transcriptions [predicted with a model](predict.md#predict-the-transcription) are named after the model.
 
 ![image: Illustration of the drop-down menu for selecting the version of the transcription](img/export/escriptorium_export_transcription_version.gif "Choosing a transcription version")
 
@@ -92,15 +92,15 @@ Once all options are set, click on the "Export" button at the bottom of the pop-
 
 As soon as the export is ready, a green message box will appear in the upper-right section of the interface, providing you with a download link. Click on "Download" to download the txt file or the zip file resulting from your export.
 
-When exporting ALTO and PAGE, the exported file is saved as a zip file containg an XML file per document-part, the corresponding images if included, as well as a METS XML file describing the ensemble.
+When exporting ALTO and PAGE, the exported file is saved as a zip file containing an XML file per document-part, the corresponding images if included, as well as a METS XML file describing the ensemble.
 
 When exporting plain text, clicking on "Download" will redirect you to a new URL, displaying the plain text. All the transcriptions are concatenated as a single text file.
 
 ![image: Illustration of the export](img/export/escriptorium_export_download.gif "Stating the export task and downloading the result.")
 
 !!! Tip
-    If you plan on doing several exports, we recommand to close the green message-box after each export (after downloading the file of course).  
+    If you plan on doing several exports, we recommend to close the green message-box after each export (after downloading the file of course).  
 
 ### Find previous exports
 
-Each export is provided a unique permanent link. You can save it, for example to automatically re-download it later without having to set the whole export again but it is also possible to find the links to all your previous exports in the Profile page, under the "Files" tab.<!-- todo: add link to "review and edit your profile" which should logically be : [Profile page, under the "Files" tab](walkthrough_users.md#review-and-edit-your-profile)-->  
+Each export is provided a unique permanent link. You can save it, for example to automatically re-download it later without having to set the whole export again but it is also possible to find the links to all your previous exports in the [Profile page, under the "Files" tab](users.md#review-and-edit-your-profile).

docs/walkthrough_import.md → docs/import.md

@@ -1,12 +1,12 @@
 ---
-title: Import to eScriptorium
+title: Import data into eScriptorium
 summary: About import features in eScriptorium.
 authors:
     - Alix Chagué, Hugo Scheithauer, Floriane Chiffoleau
 date: 2023-02-13
 ---
 
-# Walkthrough: import to eScriptorium
+# Import data into eScriptorium
 
 eScriptorium allows users to import data from various types of external resources.
 
@@ -39,11 +39,11 @@ Go to `{base_url}/document/{document-id}/images/` to access the main dashboard t
 
 ### 3. From IIIF
 
-Go to `{base_url}/document/{document-id}/images/` to access the main dashboard to control images. Locate the "**Import**" button just under the drag-and-drop rectangle. Click on the "**Import**" button, then the "**Images (IIIF)**" option, then enter the URL of an IIIF manifest. All the images associated with the manifest are then copied locally, as well as the metadata, which are visible in the "**Description**" tab.
-
-??? Note "What is IIIF"
+!!! Note
     IIIF is an international framework to share images guaranteeing interoperability. For more information, check [iiif.io](https://iiif.io/)
 
+Go to `{base_url}/document/{document-id}/images/` to access the main dashboard to control images. Locate the "**Import**" button just under the drag-and-drop rectangle. Click on the "**Import**" button, then the "**Images (IIIF)**" option, then enter the URL of an IIIF manifest. All the images associated with the manifest are then copied locally, as well as the metadata, which are visible in the "**Description**" tab.
+
 !!! Tip  
     Example URL to try the IIIF import feature: [https://gallica.bnf.fr/iiif/ark:/12148/btv1b53026595r/manifest.json](https://gallica.bnf.fr/iiif/ark:/12148/btv1b53026595r/manifest.json)
 
@@ -64,25 +64,24 @@ Click "Upload". The model now appears in the models list.
 
 ## Import segmentation and transcription
 
-It is possible to import a layout information, with or without transcription, from XML files. 
+It is possible to import a layout information, with or without transcription, from XML files.
 
 When using this feature, it is not necessary to select the pages which will be affected by the segmentation import: the mapping is automatically calculated based on the image file name and the information contained in the XML files.
 
 Go to `{base_url}/document/{document-id}/images/` to access the main document dashboard. Locate the "**Import**" button just under the drag-and-drop rectangle. Click on the "**Import**" button, then the "**Transcriptions (XML)**" option.  
 
 A pop-up allows you to set several actions before clicking "Start importing":
 
-- Specify a name for the transcription extracted from the XML files. This name will appear in the list of [transcription versions](walkthrough_transcribe.md#transcription-versions) available for the document.  
+- Specify a name for the transcription extracted from the XML files. This name will appear in the list of [transcription versions](transcribe.md#transcription-versions) available for the document.  
 - Check the "override" option, which will have the existing segmentation removed and replaced with the imported segmentation. If unchecked, the segmentation imported from XML files will be added to the existing segmentation.
 - Select the file to import from the file browser. This file can be either a single ALTO XML or PAGE XML file, or a ZIP file containing several XML files for batch import.
 
 ![image: Demonstration of importing a transcription from a series of XML files](img/import/import_xml.gif "Importing segmentation and transcription from XML files")
 
-!!! Warning "Known bug"
-    If you delete a [transcription version](walkthrough_transcribe.md#transcription-versions) named "A" and try to import a transcription from an XML file naming it "A" as well, then the new transcription version will not be created: you need to use another name.
+!!! Warning
+    There is a [known bug](https://gitlab.com/scripta/escriptorium/-/issues/752) where if you delete a [transcription version](transcribe.md#transcription-versions) named "A" and try to import a transcription from an XML file naming it "A" as well, then the new transcription version will not be created: you need to use another name.
 
 !!! Tip  
-    When importing XML files generated with other tools such as Transkribus, it can be useful to run a segmentation task targeting only the [line masks](walkthrough_segment.md) or to pre-process the file with a tool such as [LSS](https://github.com/ponteineptique/lss).[^lss]
-
+    When importing XML files generated with other tools such as [Transkribus](https://readcoop.eu/transkribus/), it can be useful to run a segmentation task targeting only the [line masks](segment.md) or to pre-process the file with a tool such as [LSS](https://github.com/ponteineptique/lss).[^lss]
 
-[^lss]: Layout Segmentation Simplifier.
+[^lss]: Layout Segmentation Simplifier.