(Tutorials) documentation revamp

💡 Feature request

Hello, the Tutorials documentation is a great idea to ease in newcomers to the library! As I was working through the examples, I noticed that, while the texts are well-written and to the point, there’s some (maybe inherent/inevitable) inconsistency between different tutorials, as well as small (mostly grammatical) errors here and there.

The inconsistencies mentioned can range from very little nitpicks that probably only bother me (e.g. some sentences before code blocks end with a ., others with a :; poliastro is sometimes written poliastro; from astropy import units as u vs import astropy.units as u…) to more major differences between tutorials (check this and compare it to this).

Additionally, some extra work could be put into this, for example as per https://github.com/poliastro/poliastro/issues/949. An objection to this, however could very well be that: a) the text is in a pretty good state as it is, and b) a technical writer will probably get to work on this sooner or later (https://github.com/poliastro/poliastro/issues/1106)

Nonetheless, I believe small, sporadic changes can happen to polish some text sections without requiring significant effort. I could also try to make some iterations, if I can. I intend to hit up a small PR addressing only minor grammatical fixes in a little bit.

🎯 Goal

As someone who heavily focuses on the presentation of an idea/project, I think small enhancements such as these mentioned above could take the already great impression poliastro leaves on a newcomer and up it just a notch.

More importantly, I think that, at least the more impactful changes proposed, align with the project’s core principles, specifically 2 and 7. If the tutorials could somehow become even more informative in an easy manner, I believe this is a win 🚀. It’s a great practice for every FOSS project out there, too; specifically those that depend on long-term community engagement for their development and maintenance.

Let me know what you think and whether this is a sound idea/incoherent rambling/out of the project’s scope @jorgepiloto @astrojuanlu

[astrojuanlu]

An objection to this, however could very well be that:

It’s a very good observation @xlxs4. I propose we:

• Do some review of code and import inconsistencies, as you suggested
• Do some small typo and grammar correction,
• Leave large text changes to a technical writer when we apply to Google Season of Docs (hopefully next year)

@xlxs4 Do you want to take care about the first or two first points?

Also, congratulations on this excellent analysis of the repository! Loved the links to existing issues 😃

[astrojuanlu]

The problem is that no tools are available (as far as I know) to format the code from the notebooks, as they are stored in *.mystnb files.

Look!

(.venv) juanlu@voyager:~/Development/poliastro/poliastro/docs/source/examples$ jupytext --pipe black Plotting\ in\ 3D.mystnb 
[jupytext] Reading Plotting in 3D.mystnb in format mystnb
[jupytext] Executing black -
reformatted -
All done! ✨ 🍰 ✨
1 file reformatted.
[jupytext] Writing 'Plotting in 3D.mystnb' in format mystnb:myst (destination file replaced [use --update to preserve cell outputs and ids])
(.venv) juanlu@voyager:~/Development/poliastro/poliastro/docs/source/examples$ git diff
diff --git a/docs/source/examples/Plotting in 3D.mystnb b/docs/source/examples/Plotting in 3D.mystnb
index 1d227b51..de1c2994 100644
--- a/docs/source/examples/Plotting in 3D.mystnb        
+++ b/docs/source/examples/Plotting in 3D.mystnb        
@@ -3,8 +3,8 @@ jupytext:
   text_representation:
     extension: .mystnb
     format_name: myst
-    format_version: 0.12
-    jupytext_version: 1.9.1
+    format_version: 0.13
+    jupytext_version: 1.11.0
 kernelspec:
   display_name: Python 3
   language: python
@@ -23,6 +23,7 @@ from poliastro.plotting import *
 
 ```{code-cell}
 import plotly.io as pio
+
 pio.renderers.default = "notebook_connected"
 ```
 
@@ -62,9 +63,7 @@ from poliastro.util import time_range
 date_launch = time.Time("2011-11-26 15:02", scale="utc").tdb
 date_arrival = time.Time("2012-08-06 05:17", scale="utc").tdb
 
-earth = Ephem.from_body(
-    Earth, time_range(date_launch, end=date_arrival, periods=50)
-)
+earth = Ephem.from_body(Earth, time_range(date_launch, end=date_arrival, periods=50))
 ```
 
 ```{code-cell}