alix-tz/escriptorium-documentation

Source code to eScriptorium Documentation's website (powered with Mkdocs)

This GitHub repository stores the source code for the eScriptorium documentation. It is a collective initiative, open to anyone and designed to be modified by anyone.

The eScriptorium Documentation website is powered by MkDocs and hosted on readthedocs. All the source files of the pages are written in Markdown, which is a light markup language facilitating future editions.

For more information on Markdown's syntax, see the cheat-sheet.

Contribute

Anyone can contribute to this project by:

• listing errors in a dedicated issue, preferably offering solutions;
• editing the files (see below) and opening pull requests, preferably justifying the necessity of the edition;
• picking up tasks from the issues board, in particular those tagged with "help wanted".

Editions can be minor (you spot a missing s, a broken link, etc) or major (a piece of information is out-dated, you want to add a whole new page, etc). Any reasonable modification is welcome, as long as it helps keep this documentation up-to-date with the core eScriptorium application.

Edit the files and run a local test server

The following steps will allow you to locally test the success of the website's build before pushing your modifications to the project.

1. Clone this repository and move to the corresponding directory

git clone [email protected]:alix-tz/escriptorium-documentation.git
cd escriptorium-tutorial/

2. Create your own local branch

git checkout -b my-new-branch

3. Create a Python 3.8 virtual environment and install mkdocs from requirements

(with conda)

conda -n create venv python=3.8
pip install -r requirements.txt

4. Start the dev server

mkdocs serve

Open up http://127.0.0.1:8000/ in your browser to see the default home page.

Note that the local server will automatically reload the content when you save a document.

For more information on how to install and use mkdocs, see the official documentation.

escriptorium-documentation's Issues

Create theme sections in FAQ to make it easier to browse

Should the url in readthedocs be "escriptorium.rtd" in stead of "escriptorium-tutorial.rtd"?

After all, this is more than an tutorial...

Add link to "Segment" from "Import segmentation and transcription"

The "Import segmentation and transcription" mentions

• mask recalculation (See walkthrough_import.md:line-79)

Which should normally be covered in #10.

This is a reminder to add a link once #10 is fixed.

---

A remaining issue after #17

Changing the order in nav?

In #67, @FloChiff said:

If we don't do alphabetically order and stay with what we have right now, I think I would put “Export data” below “Import data” and I would also bring “Train models” before all the “manual” stuff and then put “Search” after the “Virtual keyboard”.

Add a page on how to use the tags

Walkthrough - Segment

This issue has been created for keeping track of the writing of the Segment section.

• Overwiew
• Editing lines
• Editing regions
• Reordering

fix URL to edit in Github

the URL is based on "master" instead of "main".

Add illustration to "import models"

... in walkthrough_import.md

A GIF could illustrate steps to upload the model.

• Make the demo GIF
• Add it to the subsection

---

A remaining issue after #17

Reorganize the files

• have a "basic usage" walkthrough
• breakdown the more "thorough" walkthrough into smaller files, which would be easier to maintain and update
• there could be a compilation here in charge of building a single MD file for the thorough waltkthrough

Walkthrough - Collaborate

This issue has been created for keeping track of the writing of the Collaborate section.

• Create a team or join a team
• Invite a user
• Share a project or a document
• Share a model

Add a terminology section?

I think we need to add definitions of the terminology of eScriptorium:

• What's a project?
• What's a document?
• What's training?
• etc.

Just to name a few. :)

As @alix-tz said, we could link definitions to walkthroughs they are mentioned in.

I think this idea is also linked to #49

Merge information on task monitoring and task reports

We need to gather the information on Task Monitoring and Task Reports in one place to make it easier to maintain later. Currently the information is spread in:

• walkthrough_predict.md
• walkthrough_users.md

Feed walkthrough section

• with elements from https://lectaurep.hypotheses.org/documentation/prendre-en-main-escriptorium
• create issues for sections that needs to be re-written

Add "keys" extension from Py Markdown-extension

• update the wiki
• add config for keys in mkdocs

Redo broken GIFs

Unfortunately, @FloChiff GIFs don't work on every browsers, we need to find out why, and/or to remake them so that they loop instead of stopping after 1 loop.

Add documentation on "confidence"

• toggled in "description"
• displayed in Text
• possible to play with threshold

Walkthrough - Predict

This issue has been created for keeping track of the writing of the Predict section.

• Predicting regions
• Predicting annotations

Tag/Annotation for document parts

It is possible to type the document parts (set in the ontology and applied with the 1st panel). Where do you think we should add the corresponding documentation?

Why does the Ctrl key is displayed as "^Ctrl" ?

This is a minor issue, but do we know why Mkdocs displays the Ctrl key as ^Ctrl?

See:

https://escriptorium.readthedocs.io/en/latest/transcribe/

Walkthrough - Train

• Transcription models
• Segmentation models

Use https://lectaurep.hypotheses.org/documentation/escriptorium-tutorial-en as a basis

Help needed for "Virtual Keyboard" and "Text Normalization"

I am working on #11 and I need a little more help on the two following parts, which I am not familiar with:

• Virtual Keyboard
• Text Normalization

Add how to give a user training rights?

This is done in the back-end. Do we want to include this in the documentation? It would go inside "walkthrough_administrator.md".

Ajouter les illustrations and docs/img

• extract illustrations from https://lectaurep.hypotheses.org/documentation/prendre-en-main-escriptorium
• add illustrations in folder (rename if necessary)

Switch to MkDocs

Having to write the documentation in Sphinx is a real slow down so I just switched the compiler to what looks like a Markdown based option: MkDocs.

This could provide more document :

• https://www.mkdocs.org/

Precision needed for the 'draw annotation' part

I just tried the drawing of an annotation part on a document using the tutorial, and it was harder than I though because I didn't exactly know how to draw the annotation.
In the case of an annotation in the form of a rectangle, it is pretty easy because you only need to click once on your mouse from the top left corner of your rectangle and then go to the bottom right corner of it and then stop clicking in order to have your rectangle.
With the polygon, I struggle to find how to release the polygon once it is done (I apparently simply needed to double-click on my mouse to do it).
I think it might be useful to explain clearly on the walkthrough how we can draw each annotation.

Walkthrough - User related features

• build subsections
• feed subsections

This section of the tutorial intends to detail actions avaiable through the user's menu.

An overview page for elements that are not related to one step in particular

we need a page with information on the panels for example, but I can imagine other features would need to be described in a sort of "lexicon" page.

Get more information on Task monitoring and Task reports

cf. #33 and #21

I asked for clarifications on Gitter.

Walkthrough - Export

This issue has been created for keeping track of the writing of the Export section.

• Exporting models
• Exporting annotations

Walkthrough - Transcribe

This issue has been created for keeping track of the writing of the Transcribe section.

Spell checking on english pages

None of us are native English speakers so we could use some spell checking and suggestions to improve the structure of sentences.

Walkthrough - Import

• Import images
• Import models
• Import segmentation and transcription

Use https://lectaurep.hypotheses.org/documentation/escriptorium-tutorial-en as a basis

A walkthrough for the /admin/ page?

Should we make a walkthrough for the administration page? Like giving some indication on how to manage an eScriptorium instance as an admin, giving rights to users, etc.

Or, is it unnecessary since it's based on Django site administration features, and thus users having access to it may already have general knowledge about it?

Fix unicode character showing a mouse in shortcut key map

see in #49

The chosen character might not be known to all browsers or systems

Some css work to do on the "github" footer

The github footer, on the index, is hiding the last walkthrough "Administrator," I think we can mess with the css a bit to fix that!

Add link to "Transcribe" from "Import segmentation and transcription"

The "Import segmentation and transcription" mentions

• transcription versions (See walkthrough_import.md:line-69)

Which should normally be covered in #11.

This is a reminder to add a link once #11 is fixed.

---

A remaining issue after #17

Walkthrough - Annotate

• Region and line types edit: will actually be covered in "segment", I believe
• Image annotations
• Text annotations
• Annotation Components

Edit the Quick start page

Create the structure of the quick start page, but only once the walkthrough is complete.

Add to wiki: cheatsheet for Markdown syntax for Mkdocs and extensions

See : https://github.com/alix-tz/escriptorium-tutorial/wiki/Markdown-in-Mkdocs

Walkthrough - Search

• Activate search
• Use search

Create a "external doc" section

• see docs in https://lectaurep.hypotheses.org/documentation/prendre-en-main-escriptorium
• and https://github.com/alix-tz/escriptorium-doc-finder

Describe how to move a document from a project to another

It might require creating an overall section for document management.

Maybe this section could include explanation on the vocabulary regarding projects/documents/document parts, as well.

Add a shortcuts section?

I was thinking it could be useful to add a page where we would centralize all useful shortcuts, in addition to the ones we document in the different walkthroughs.

I think it could be useful for people that just want to get a quick handle on the app and not go through every walkthrough.

What do you think? 🤔