Mandatory Reading

HephIA Product Documentation.

MANDATORY READING

Install Jupyter Book

Glossary

Section :

• Markdown : A line begins with on # symbol or more, the more they are # symbols the more the depth of the section will be. Let’s state that a single # is at level 0, then ## is at level 1, etc…
• Jupyter Book : A line begins with and only with a single # symbol. When they are more single # symbols, you will encounter Jupyter Book displaying issues.

Conclusion : Be sure to have a single # on all your markdown and jupyter notebook files.

Subsection :

• Markdown : Wu usually call subsections Headers with more than a single # symbol.
• Jupyter Book : It is a dedicated term to describe a one deeper level hierarchy within a particular chapter section. It is composed of a regular file with a SINGLE Header 1 # describing the section (in Jupyter Book sense) title and then regular content. Then other files which each also have a SINGLE Header 1 # describing the subsection title plus additional regular content.

Conventions

snake_case usage

The only current exception for snake_case are acronyms for example :

• MI : Mutualized Information
• NMI : Normalized Mutualized Information
• MCC : Matthews Correlation Coefficient
• …

List of files or text blocs that follow the snake_case convention :

• Python code
• Jupyter Book reference section labels, i.e. (ref_to_particular_section)=
  • Jupyter Book website link on reference section labels.
  • A dedicated section to syntactic conventions for Jupyter Book section reference ((ref_to_particular_section)=) is few section below.

EVERY file of production HephIA documentation MUST use snake case convention

No exception at this moment concerning both above statements.

EVERY folder of production HephIA documentation MUST use CamelCase convention

No exception at this moment concerning both above statements.

Syntactic convention for Jupyter Book

Syntactic rules of thumb to make references toward others sections

They consist of :

1. Wrote your references in snake_case
2. Chapter’s file name must ends with _chapter_home: my_chapter_called_toto_chapter_home
3. Section’s file name must ends with _section_home : my_section_home
4. Start with def_ concepts definitions
5. Similar Header title in multiple files

Wrote your references in snake_case

When you declared a reference key above any section, they (ref_to_particular_section)= be in snake_case as in following example :

(my_header_2_section)=
## My Header 2 section 

It will be used as follows :

[one ref toward my Header 2 section](my_header_2_section)

More examples and advanced usages are exposed on official Jupyter Book section about References and cross-references.

We have seen that snake_case handles how reference keys MUST be named.

End the file name’s chapter with _chapter_home

Each chapter home file MUST ends with _chapter_home. Moreover, this file is written at the same depth level that chapter folder as illustrated below :

/Chapters/chapter1_home_chapter.md
/Chapters/Chapter1/file1.md

End section home file with _section_home

Each section’s home file ends with _section_home. Moreover, this file is written at the same depth level that section folder and NEVER in the section folder itself as illustrated below :

/Chapters/chapter1_home.md
/Chapters/Chapter1/section_x_section_home.md
/Chapters/Chapter1/SectionX/section_x_topic1.md
/Chapters/Chapter1/SectionX/section_x_topic2.md

Start with def_ concepts definitions

Each definition of Chapters/CoreConcepts begin

Each reference keyword, (def_my_concept)=, associated with a definition begins with def_ as in below example :

The file /Chapters/CoreConcepts/Clustering/cluster_id.md will have the following Header 1 # section :

(def_cluster_id)=
# ClusterId

Similar Header title in multiple files

The reference key is often similar to the section title as shown above but in some cases there can be multiple sections sharing the same title. Let’s illustrate it with the official documentation. There is two files with the same name clustering_home.md in different folders as expose below :

# Ex 1
/Chapters/Algorithms/UnsupervisedLearning/clustering_home.md
/Chapters/CoreConcepts/clustering_home.md

The rule to name adequately the reference key is to end the string value with the name of the folder which has as sibling other folders within are included files with the same name as illustrated here :

The reference key in /Chapters/Algorithms/UnsupervisedLearning/clustering_home.md file could be :

(clustering_home_algorithms)=
# Clustering

The reference key in /Chapters/CoreConcepts/clustering_home.md file could be :

(clustering_home_core_concept)=
# Clustering

Abstracted examples

You can also skip to the next section untitled “Repository organization” by clicking on this sentence.

Let suppose another files’ hierarchy :

Chapters/A/B/C/D1/toto.md
Chapters/A/B/C/D2/toto.md
Chapters/A/B/C/toto.md
Chapters/A/B/D/toto.md
Chapters/A/B/toto.md

In Chapters/A/B/C/D1/toto.md file, the reference key MUST be :

(toto_d1)=
# Toto

In Chapters/A/B/C/D2/toto.md file, the reference key MUST be :

(toto_d2)=
# Toto

In Chapters/A/B/C/toto.md file, the reference key MUST be :

(toto_c)=
# Toto

In Chapters/A/B/D/toto.md file, the reference key MUST be :

(toto_d)=
# Toto

In Chapters/A/B/toto.md file, the reference key MUST be :

(toto_a)=
# Toto

Repository organization

Minimal example

A minimal example of how a Jupyter Book can be done is within JupyterBookMinimalExample folder. It contains various pieces of code with associated documentation of how do numerous tasks from which the user experience derives.

Examples are everywhere, from the hierarchy of files to inner code explained samples passing by configuration files setting up.

Official documentation.

It is in folder HephIAProductDocumentation at project root folder. It gathers every necessary stuff to have a stunning documentation.

Content rule of thumbs

They MUST BE FOLLOWED on the official documentation even if they are not in the example book.

• Clustering algorithm MUST HAVE their default predictor documentation included in.
• …

User documentation.

It takes the form of a Jupyter Book, i.e. a friendly user interface to read, write, and execute, depending on file’s nature, three type of files :

• Markdown file (markdown.md)
• Jupyter Notebook (notebooks.ipynb)
• MyST Markdown Notebook (markdown-notebooks.md)
  • MyST syntax cheat sheet

How to build a Jupyter Books in this repository.

Use the build Jupyter Book command.

Go to this repository root and run commands :

• jupyter-book build Jupyter_Book_Minimal_Example/ to build the Jupyter Book tutorial.
• jupyter-book build HephIA_Product_Documentation/ to build the HephIA Product Documentation.

How to clean a previous built book.

Use the clean Jupyter Book command.

The minimal command is : jupyter-book clean My_Path_To_My_Jupyter_Book_Folder/

The full command is : jupyter-book clean My_Path_To_My_Jupyter_Book_Folder/ --all. But it cleaned also the Jupyter Book cache due to --all option.

When should you use clean command ?

• When you suspect an unexpected displayed render in regard to what you think (do not forget that you can misunderstand the situation) of what your code is supposed to do.
• If you reordered your files displaying through the _toc.yml, it seems that it is also necessary, if not you risk keeping the previous ordering.
• Other nasty reasons I didn’t fall on yet.

Jupyter Book additional documentation.

This section contains additional materials about how use Jupyter Book in practise.

IT IS NOT THE WHOLE Jupyter Book DOCUMENTATION, IT ALSO MUST have been explored alongside this project for a full understanding of it.

This section gathers various notes and examples taken during the Jupyter Book learning process to facilitate the mastery of this tool to work efficiently together and for the pleasure of all, i.e. us the HephIA teams and especially for our Customers.

Jupyter Book Cheatsheet

How to name your pages in the left panel.

Our convention is the follow for listed files types :

• markdown : The first line of the file MUST BE THE UNIQUE Header1 # of the whole notebook.
• jupyter-notebook : The first cell MUST BE a markdown one with THE UNIQUE Header1 # of the whole notebook.

NO OTHER Header1 # are allowed in the rest of the file due to numbering page potential issues explained on official documentation and also at below section.

Files displaying ordering.

Files documentation displaying follows the order in which files are written _toc.yml.

Subsection mechanism.

They are declared in _toc.yml file as follows :

chapters:
- file: path/to/chapter1
- file: path/to/chapter2 # This is the file of chapter2 home page.
  sections: # key used to declared subsections.
  - file: path/to/chapter2/section1 # First file of your subsection.
  - file: path/to/chapter2/section2 # Second file of your subsection.

Subsection can be nested to others as shown below :

- file: path/to/chapter2 # This is the file of chapter2 home page.
  sections: # key used to declared subsections.
  - file: path/to/chapter2/section1 # First file of your subsection.
  - file: path/to/chapter2/section2WithSubsections # This is the file of section2 homepage within chapter2.
    sections: # key used to declared subsections.
     - file: path/to/chapter2/section2/file1 # First file of your nested subsection.
     - file: path/to/chapter2/section2/file2 # Second file of your nested subsection.
  - file: path/to/chapter2/section3 # Third section of your subsection which is after the level 2 nested subsections.

Let’s suppose you organize your file hierarchy as follows when you deal with subsections.

If you put subsections files into a given folder, let’s call it MySubsection, you do not need to name the subsection homepage file with the exact same name as the folder where subsections files are in. It is illustrated above with the subsection homepage file section2WithSubsections at path path/to/chapter2/. The content of these subsections are files file1 and file1 within path/to/chapter2/section2/ path.

Numbering displaying issues.

It can be possible than if you misused the Heard 1 # for other reason than giving a single title to your sections and subsections a numbering displaying issue will rise. It will be the case only especially if you use the numbered TOC file option. It will result of missing number at least at section level, i.e. Header 1 #. It will be often due to multiple Header 1 # declarations into a single file, thus a single # meaning a section in Jupyter Book sense, multiple ones into a single file will create multiple section at the file level following the engine chosen by Jupyter Book which is Sphinx engine.

More details are available in this Jupyter Book webpage.

Useful resources

Parse and render settings within parse key when inner key myst_enable_extensions is used.

Jupyter-Notebook

Jupyter-Notebook Cheat Sheet - 1 Jupyter-Notebook Cheat Sheet - 2 Jupyter Notebook Cheat Sheet: A Beginner’s Guide to Jupyter Notebook

Markdown

Basics

• Markdown Guide
• The Ultimate Markdown Cheat Sheet - Towards Data Science
• Markdown Github Cheat Sheet

Others

• IFrame within markdown files
• Markdown supports inline HTML
• What is the difference between block level and inline level?
  • HTML summary about block and inline levels
    • There are two display values: block and inline
    • A block-level element always starts on a new line and takes up the full width available
    • An inline element does not start on a new line and it only takes up as much width as necessary
    • The element is a block-level and is often used as a container for other HTML elements
    • The element is an inline container used to mark up a part of a text, or a part of a document

Developer documentation, i.e. HephIA core library.

MANDATORY READING.

Current product documentation takes form of multiple Jupiter-Notebooks. To prevent merge conflict about Jupiter-Notebooks themselves, i.e. their JSON keys.

You must be sure that upgraded notebooks have been cleared, i.e. every output must be empty.

AFTER EACH MODIFICATION OF ONE OF THEM, BEFORE ANY COMMIT, YOU MUST RUN THESE Jupyter-Notebook COMMANDS IN FOLLOWING ORDER :

• RUN ALL CELLS : Cell -> Run All
• REBOOT KERNEL & CLEANING OUTPUTS : Kernel -> Restart & Clean Output
  • Except if you have ONLY markdown cells.
• SAVE your progress : ctrl - S

ONCE IT IS DONE YOU ARE ALLOWED TO COMMIT.

Annexes