Feature/doc guide #622

NicolasColombi · 2023-01-12T16:33:23Z

Changes proposed in this PR:

Fix broken links in tutorials and guides
Fix table of content and wrong heading levels
Fix rendered Table of Content in the Website

How:

Switch from a mix of Html and MarkDown to only MarkDown like this:[My header](#My-header) and ## My header for the table of content and the header respectively.
Add blank line before and after the headings and add 1 blank space after # (Best practice according to Markdown guide)
Rearrange Table of Content so that only the main headers are displayed

PR Author Checklist

Read the Contribution Guide
Correct target branch selected (if unsure, select develop)
Source branch up-to-date with target branch
Documentation updated
Tests updated
Tests passing
No new linter issues

PR Reviewer Checklist

1) Fix headings 2) Fix typo in content structure: coniguration --> configuration

1) add table of content and link for section: 7. Run a jupyter Notebook on Euler and section 8. Trouble shooting 2) add blank line before and after the headings 3) add 1 blank space after #

Modify file: doc/guide/guide_Euler.ipynb Possible fix to the wrong outline of the content structure in the website that shows guide_Euler.ipynb.

…t/climada_python into feature/doc_guide

emanuel-schmid · 2023-01-16T16:15:05Z

doc/guide/Guide_Configuration.ipynb

+    "\n",
+    "## 1. <a id=\"Const\"> Constants </a>\n",


For the notebook itself it doesn't matter much, but sphinx (which is part of the documentation build) doesn't like too many spaces in a title.

Suggested change

"\n",

"## 1. <a id=\"Const\"> Constants </a>\n",

"## 1. <a id=\"Const\">Constants</a>\n",

I read in the Markdown guide that it was best to put a blank line before and after the heading # and I thought it might be the reason of the wrong display in the website (Which was not...) Should I remove those blank lines for each #heading ?

Also, in the last commit I switched to only markdown like this:[Access to Euler](#access-to-euler) and ##Access to Euler for the table of content and cell respectively, since @peanutfun suggested that the mix of markdown and html might produce the wrong outline in the website. I just checked and it doesn't seem to change.

The main issue is that the headings with two ## are not displayed, only headings with three ###.
I will try few exploratory commits just to see how it changes when I mess with the table of contents.

Do you have any ideas of a possible reason @emanuel-schmid @peanutfun ?
Thank you!

@emanuel-schmid I changed the headers to this style: # 1. My header, so there should not be the problem of spaces now

Sorry but I don't quite understand... 😕

At first the structure of the headers were like this:

## 1. <a id=\"link_to_my_header\"> My header name </a>

where the link_to_my_header is written in the content section like this:

[My header name](#link_to_my_header)

Since with Lukas we thought that it might have caused the problem on the website I switched to only markdown like this:

## 1. My header name

and in the content:

[My header name](#my-header-name)

Therefore, the problem you mention of having spaces in the header like this: ## 1. <a id=\"Const\"> Constants </a>\n is indirectly also resolved.

Sorry I missed what the "problem on the website" is. Is it that the links are not working?
Are they working after the link notation is removed - or are they just not displayed as links anymore?
If they are just not displayed as links on the website anymore - it's a pity somehow since they used to be working when you opened the notebook in jupyter.

@emanuel-schmid Sorry I wasn't clear with what the problem was, the links worked before and works still now. The problem is (was) that in the website the contents were rendered wrong as you can see here on the top right corner under Content. After the changes it looks right: check here. This was due to the fact that in the jupyter notebook doc/guide/Guide_Euler.ipynb the content section had a wrong header level of ### instead of ##. After switching to level ## the content is rendered right in the website.

Putting all headings aligned.

This reverts commit e8d33f1.

Adding number for headings of level 2: ##

This reverts commit 0049626.

peanutfun · 2023-01-17T08:51:04Z

I gave it a try myself and could not make it work. I think the issue is that every subheading is placed in its own notebook cell. Maybe we should merge these cells? I would also argue that we do not need a new heading for every single instruction.

Edit: See #622 (comment)

peanutfun · 2023-01-17T08:57:18Z

doc/guide/Guide_Euler.ipynb

@@ -11,42 +11,51 @@
   "cell_type": "markdown",
   "metadata": {},
   "source": [
+    "\n",
    "### Content\n",


@NicolasColombi Here's the issue: The very first subheading has the wrong level. The contents sidebar only lists the headings with the same level afterwards. This should fix it:

Suggested change

"### Content\n",

"## Content\n",

@peanutfun Ahh that was it! Thank you Lukas, tomorrow evening I will fix it in all the guides.

Co-authored-by: Lukas Riedel <[email protected]>

Change header level of content from ### to ## in doc/guide/guide_CLIMADA_Tutorial.ipynb. This change should fix the wrong displayment of contents in the website, as it did for doc/guide/guide_Euler.ipynb.

doc/guide/Guide_Euler.ipynb

Co-authored-by: Lukas Riedel <[email protected]>

Fix broken link in website by adapting the anchor in the content section of doc/guide/Guide_Euler.ipynb.

Redo table of content of doc/guide/guide_Git_Developement.ipynb. From html to markdown.

Fix two headings in contents that displayed wrong because they contained ``.

Remove `` from the heading itself and not only from the content

Split images and Headers in two different cells. Having them in the same cell caused the links to not work.

Files changed: 1) guide/Guide_Configuration.ipynb 2) guide/Guide_Euler.ipynb 3) guide/Guide_Git_Development.ipynb 4) tutorial/climada_engine_unsequa.ipynb Changes: - Only Mardown and no html - Change in format of contents

Files changed: 1) guide/Guide_CLIMADA_Tutorial.ipynb 2) guide/Guide_Continuous_Integration_and_Testing.ipynb 3) guide/Guide_Miscellaneous.ipynb 4) guide/Guide_Py_Performance.ipynb 5) guide/Guide_PythonDos-n-Donts.ipynb 6) tutorial/climada_engine_unsequa_helper.ipynb Changes: - Only Mardown and no html - Change in format of content

Files changed: 1) climada_python/README.md 2) doc/tutorial/0_intro_python.ipynb 3) doc/tutorial/climada_engine_CostBenefit.ipynb 4) doc/tutorial/climada_entity_Exposures_polygons_lines.ipynb

emanuel-schmid · 2023-01-27T14:40:07Z

Thanks a lot! Are you still working on this @NicolasColombi ?
I'll be happy to review otherwise. But could you please undo the re-plotting in doc/tutorial/climada_engine_unsequa.ipynb - or indicate why we have new plots.
And could you describe the three fixes in some more detail, especially 1 and 3?

peanutfun · 2023-01-27T15:05:27Z

Maybe I could jump in here and give a bit more context: The new documentation theme features an automated "Contents" overview of each page on the right hand side. It is built automatically from the headings in the underlying document. When the heading levels are not consistent, this overview is simply wrong. An example:

Nicolas fixes most of these issues here. Additionally, many tutorials feature self-made table of contents that use HTML links. Since Markdown supports in-document links without HTML, we thought it might be better to have "clean" Markdown and remove the HTML tags.

NicolasColombi · 2023-01-28T10:15:49Z

@emanuel-schmid Yes you can review the PR, it should be finished :) I will undo the re-plotting first thing monday morning.

Thanks @peanutfun for the context ;)

Undo re-plotting doc/tutorial/climada_engine_unsequa.ipynb

This reverts commit 6fcefc2.

Undo re-plotting of doc/tutorial/climada_engine_unsequa.ipynb

the environment creation step took so long that I got afraid it was swapping /:

defaults channel is mandatory

emanuel-schmid · 2023-02-08T13:36:29Z

🙌 Thanks a lot!

NicolasColombi added 4 commits January 12, 2023 10:51

Fix heading of doc/guide/guide_Configuration.jbynb

b4d6f8c

1) Fix headings 2) Fix typo in content structure: coniguration --> configuration

Add blank line before headers

6e168b4

Fix headings of doc/guide/Guide_Euler.ipynb

5deacbe

1) add table of content and link for section: 7. Run a jupyter Notebook on Euler and section 8. Trouble shooting 2) add blank line before and after the headings 3) add 1 blank space after #

Merge branch 'develop' into feature/doc_guide

591cca8

peanutfun changed the base branch from main to develop January 13, 2023 13:53

emanuel-schmid and others added 3 commits January 16, 2023 15:17

Merge branch 'develop' into feature/doc_guide

58a8209

Fix wrong content outline in the website

0b2ad89

Modify file: doc/guide/guide_Euler.ipynb Possible fix to the wrong outline of the content structure in the website that shows guide_Euler.ipynb.

Merge branch 'feature/doc_guide' of https://github.com/CLIMADA-projec…

58edb54

…t/climada_python into feature/doc_guide

emanuel-schmid reviewed Jan 16, 2023

View reviewed changes

NicolasColombi added 4 commits January 16, 2023 17:39

Exploratory commit

e8d33f1

Putting all headings aligned.

Revert "Exploratory commit"

e676b4c

This reverts commit e8d33f1.

Exploratory commmit 2

0049626

Adding number for headings of level 2: ##

Revert "Exploratory commmit 2"

9f96fc2

This reverts commit 0049626.

peanutfun reviewed Jan 17, 2023

View reviewed changes

Update doc/guide/Guide_Euler.ipynb

1e74648

Co-authored-by: Lukas Riedel <[email protected]>

NicolasColombi marked this pull request as ready for review January 18, 2023 08:49

NicolasColombi added 2 commits January 18, 2023 10:59

Fix wrong content displaying of guide

2db277d

Change header level of content from ### to ## in doc/guide/guide_CLIMADA_Tutorial.ipynb. This change should fix the wrong displayment of contents in the website, as it did for doc/guide/guide_Euler.ipynb.

Merge branch 'develop' into feature/doc_guide

a6c971c

peanutfun reviewed Jan 18, 2023

View reviewed changes

doc/guide/Guide_Euler.ipynb Outdated Show resolved Hide resolved

NicolasColombi and others added 10 commits January 18, 2023 14:18

Update doc/guide/Guide_Euler.ipynb

78fa4be

Co-authored-by: Lukas Riedel <[email protected]>

Fix broken link in website

f901e25

Fix broken link in website by adapting the anchor in the content section of doc/guide/Guide_Euler.ipynb.

Fix broken links doc/guide_CLIMADA_tutorial.ipynb

3967414

Fix broken links in guide_Git_Developement.ipynb

e583067

Redo table of content of doc/guide/guide_Git_Developement.ipynb. From html to markdown.

Fix doc/guide/Guide_Git_Developement content

e8c1bb1

Fix two headings in contents that displayed wrong because they contained ``.

Second try to fix problem of previous commit

9fb13a1

Remove `` from the heading itself and not only from the content

Update content of doc/guide/Guide_Git_Developement

ae93326

Split images and Headers in two different cells. Having them in the same cell caused the links to not work.

Fix content in website of guides and tutorials

acf3a53

Files changed: 1) guide/Guide_Configuration.ipynb 2) guide/Guide_Euler.ipynb 3) guide/Guide_Git_Development.ipynb 4) tutorial/climada_engine_unsequa.ipynb Changes: - Only Mardown and no html - Change in format of contents

Fix content

ab704b6

Files changed: 1) climada_python/README.md 2) doc/tutorial/0_intro_python.ipynb 3) doc/tutorial/climada_engine_CostBenefit.ipynb 4) doc/tutorial/climada_entity_Exposures_polygons_lines.ipynb

Fix content

2ffba97

NicolasColombi and others added 15 commits January 30, 2023 11:36

Undo re-plotting

6fcefc2

Undo re-plotting doc/tutorial/climada_engine_unsequa.ipynb

Merge branch 'develop' into feature/doc_guide

f4b8ba1

Revert "Undo re-plotting"

7174d2f

This reverts commit 6fcefc2.

Undo re-plotting

38e906a

Undo re-plotting of doc/tutorial/climada_engine_unsequa.ipynb

Merge branch 'develop' into feature/doc_guide

22f9e36

Merge branch 'develop' into feature/doc_guide

af940f2

Tutorial Guide: switch bullet point character to '-'

c96e5e9

env_docs conda environement for readthedocs updated

ec9f284

the environment creation step took so long that I got afraid it was swapping /:

env_docs conda environement for readthedocs fixed

d09419f

defaults channel is mandatory

env_docs conda environement for readthedocs myst-parser added

b71ab40

env_docs conda environement for readthedocs sphinx-markdown added

560c196

env_docs conda environement for readthedocs

3ed816b

Tutorial Guide: switch <br> to \

af6d9eb

Configuration guide: cosmetics

e1e1a30

Euler Guide: fix intra doc links and re-arrange doc structure (Conda)

63ab51a

emanuel-schmid mentioned this pull request Feb 8, 2023

Python module docs empty because 'sparse' is not part of env_docs.yml (anymore) #647

Closed

emanuel-schmid added 3 commits February 8, 2023 12:29

Test & CI Guide cosmetics

2558ff9

guide Git cosmetics

90833a9

Tutorial unsequa helper cosmetics

c4b4661

emanuel-schmid merged commit 82ee7b0 into develop Feb 8, 2023

emanuel-schmid deleted the feature/doc_guide branch February 8, 2023 13:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/doc guide #622

Feature/doc guide #622

NicolasColombi commented Jan 12, 2023 •

edited

Loading

emanuel-schmid Jan 16, 2023

NicolasColombi Jan 16, 2023

NicolasColombi Jan 18, 2023

emanuel-schmid Jan 18, 2023

NicolasColombi Jan 18, 2023 •

edited

Loading

emanuel-schmid Jan 18, 2023

NicolasColombi Jan 18, 2023 •

edited

Loading

peanutfun commented Jan 17, 2023 •

edited

Loading

peanutfun Jan 17, 2023

NicolasColombi Jan 18, 2023

emanuel-schmid commented Jan 27, 2023

peanutfun commented Jan 27, 2023

NicolasColombi commented Jan 28, 2023 •

edited

Loading

emanuel-schmid commented Feb 8, 2023

	"\n",
	"## 1. <a id=\"Const\"> Constants </a>\n",
	"## 1. <a id=\"Const\">Constants</a>\n",

Feature/doc guide #622

Feature/doc guide #622

Conversation

NicolasColombi commented Jan 12, 2023 • edited Loading

PR Author Checklist

PR Reviewer Checklist

emanuel-schmid Jan 16, 2023

Choose a reason for hiding this comment

NicolasColombi Jan 16, 2023

Choose a reason for hiding this comment

NicolasColombi Jan 18, 2023

Choose a reason for hiding this comment

emanuel-schmid Jan 18, 2023

Choose a reason for hiding this comment

NicolasColombi Jan 18, 2023 • edited Loading

Choose a reason for hiding this comment

emanuel-schmid Jan 18, 2023

Choose a reason for hiding this comment

NicolasColombi Jan 18, 2023 • edited Loading

Choose a reason for hiding this comment

peanutfun commented Jan 17, 2023 • edited Loading

peanutfun Jan 17, 2023

Choose a reason for hiding this comment

NicolasColombi Jan 18, 2023

Choose a reason for hiding this comment

emanuel-schmid commented Jan 27, 2023

peanutfun commented Jan 27, 2023

NicolasColombi commented Jan 28, 2023 • edited Loading

emanuel-schmid commented Feb 8, 2023

NicolasColombi commented Jan 12, 2023 •

edited

Loading

NicolasColombi Jan 18, 2023 •

edited

Loading

NicolasColombi Jan 18, 2023 •

edited

Loading

peanutfun commented Jan 17, 2023 •

edited

Loading

NicolasColombi commented Jan 28, 2023 •

edited

Loading