New Read the Docs tutorial, part I #8428

astrojuanlu · 2021-08-18T14:50:25Z

This is the first pull request (hopefully out of many more to come) for the new Read the Docs tutorial proposed in #8106 in the context of the CZI grant. Paraphrasing @evildmp, it is by no means finished, but almost complete 🙂

Rendered version: https://docs--8428.org.readthedocs.build/en/8428/tutorial/

This pull request intends to cover chapter 2 of the table of contents originally proposed in #8106:

Getting started
1. Preparing our project on GitHub
2. Importing our project to Read the Docs
3. Basic configuration changes

In light of the recent conversations around #8410, I have added some detailed information about the signup process, since the tutorial is aimed at newcomers and we don't assume advanced GitHub knowledge.

The template mentioned in the tutorial is this one, at the moment living on my personal GitHub account before it is accepted:

https://github.com/astrojuanlu/tutorial-template/

astrojuanlu · 2021-08-18T21:51:49Z

This is ready for review. Pinging @readthedocs/advocacy and also @nienn, in case she can offer a (much needed!) newcomer perspective and look at the tutorial with fresh eyes.

About your comment on #8410 (comment):

what I most missed was a brief introduction, without going into too much technical detail, about what is Read the Docs App, what problems is it trying to solve, what are it's dependencies and a clear, very much simplified, path that I would need to follow in order to get from where I was to having a complete working documentation project.

I haven't included such explanation yet (that would be part of section 1 "The Read the Docs way" as per our original proposal) but hopefully I can do it soon (perhaps in a future pull request).

ericholscher

This is wonderful. 🎉 🎉

Lots of little nitpicks, but overall I think it's great and I'm super stoked to have it. ❤️

ericholscher · 2021-08-18T22:14:41Z

docs/tutorial/index.rst

+You will fork a fictional software library
+similar to the one developed in the :doc:`official Sphinx tutorial <sphinx:tutorial/index>`.
+No prior experience with Sphinx is required,
+and you can follow this tutorial without having done the Sphinx one.


This reads nicely, and gives the user somewhere to learn more if needed. Love it 💯

docs/tutorial/index.rst

ericholscher · 2021-08-18T22:32:25Z

docs/tutorial/index.rst

+You can now proceed to make some basic configuration adjustments.
+For that, click on the "⚙ Admin" button, which will open the Settings page.


I think we need to tell them that this is on the project page.

We should also clarify our language, is it Admin or Settings?

Suggested change

You can now proceed to make some basic configuration adjustments.

For that, click on the "⚙ Admin" button, which will open the Settings page.

You can now proceed to make some basic configuration adjustments.

Navigate back to the *project page* click on the "⚙ Admin" button, which will open the Settings page.

Good point, will clarify

We should also clarify our language, is it Admin or Settings?

Admin has a Settings section, as well as Advanced Settings, Edit Versions... but there is no "Admin page" per se. Not sure how to reword this.

ericholscher · 2021-08-18T22:33:41Z

docs/tutorial/index.rst

+To do so, click on the "Notifications" link on the left,
+type the email where you would like to get the notification,
+and click the "Add" button.
+After that, your email will be shown under "Existing Notifications".


The UX on this page is so bad :( Really need to improve it.

Yep, it's ugly 😓

ericholscher · 2021-08-18T22:34:46Z

docs/tutorial/index.rst

+
+To enable that functionality, first click on the "Advanced Settings" link on the left
+under the "⚙ Admin" menu, check the "Build pull requests for this project" checkbox,
+and click the "Save" button at the bottom of the page.


We should definitely make this easier to do :(

Or evaluate the cost of making it opt-out? I hypothesize that most projects use only the default branch anyway (no extra $ on our side), and those who do use pull requests would really appreciate having this feature but they might not know about it.

Yea, I could be convinced, tho I worry it's the same as pdf/epub, where if it's on by default most users still won't use it (and might get annoyed by it). I think we need to promote it more, either way.

docs/tutorial/index.rst

Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>

astrojuanlu · 2021-08-19T08:09:09Z

Thanks @ericholscher for the super thorough review! Addressed the comments.

astrojuanlu · 2021-08-19T08:21:55Z

Hmm the checks are failing with this error:

docs-lint run-test: commands[0] | rstcheck -r .
./tutorial/index.rst:124: (ERROR/3) Undefined substitution referenced: ":arrows_counterclockwise:".

however, the emoji renders correctly. Any idea of what might be happening here?

stsewd · 2021-08-19T14:46:23Z

@astrojuanlu you need to update this file https://github.com/readthedocs/readthedocs.org/blob/master/docs/.rstcheck.cfg

astrojuanlu · 2021-08-19T15:16:26Z

Thanks @stsewd! Basically all emojis then... I added a few more to make this PR pass.

ericholscher · 2021-08-20T15:51:35Z

@astrojuanlu you need to update this file https://github.com/readthedocs/readthedocs.org/blob/master/docs/.rstcheck.cfg

That seems silly :(

ericholscher

Looks great!

ericholscher · 2021-08-24T15:02:23Z

docs/.rstcheck.cfg

@@ -1,7 +1,7 @@
 [rstcheck]
 ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete
 ignore_roles=djangosetting,setting,featureflags,buildpyversions
-ignore_substitutions=org_brand,com_brand,:smile:
+ignore_substitutions=org_brand,com_brand,:smile:,:arrows_counterclockwise:,:heavy_plus_sign:,:tada:,:heart:,:pencil2:


Would be nice if we could just say ignore :*:

That won't work apparently https://github.com/myint/rstcheck/blob/3f92957478422df87bd730abde66f089cc1ee19b/rstcheck.py#L265-L266 and rstcheck seems to be unmaintained.

docs/glossary.rst

docs/tutorial/index.rst

ericholscher · 2021-08-24T15:05:37Z

docs/tutorial/index.rst

 Basic configuration changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

 You can now proceed to make some basic configuration adjustments.
-For that, click on the "⚙ Admin" button, which will open the Settings page.
+Navigate back to the :term:`project page`


ericholscher · 2021-08-24T15:06:09Z

docs/tutorial/index.rst

@@ -268,3 +281,6 @@ If you click on the "Details" link while it is building,
 you will access the build logs,
 otherwise it will take you directly to the documentation.
 When you are satisfied, you can merge the pull request!
+
+That's the end of the tutorial for now,


for now feels weird, but I don't have a great suggestion.

Let's just remove it?

docs/index.rst

Add beginning of tutorial with getting started instructions

b91563f

astrojuanlu mentioned this pull request Aug 18, 2021

Add documentation on "Getting started with Read the Docs" #8329

Closed

Add first steps section to the tutorial

4955c53

astrojuanlu changed the title ~~DRAFT: New Read the Docs tutorial, part I~~ New Read the Docs tutorial, part I Aug 18, 2021

astrojuanlu marked this pull request as ready for review August 18, 2021 21:48

astrojuanlu requested review from a team and nienn August 18, 2021 21:48

ericholscher reviewed Aug 18, 2021

View reviewed changes

astrojuanlu and others added 9 commits August 19, 2021 08:47

Style improvements

afb9681

Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>

Style improvement

cb86de4

Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>

More style improvements for buttons

35a188f

Move figure to more appropriate place

8720d09

Clarify that the Settings are on the project page

85f533f

Add note about ads

41a48fe

Add glossary

06860b2

Amend link location

0626dac

Animate import project workflow

b2a8346

astrojuanlu requested a review from ericholscher August 19, 2021 08:08

Ignore some more emoji substitutions

2328b35

ericholscher approved these changes Aug 24, 2021

View reviewed changes

astrojuanlu added 4 commits August 24, 2021 17:39

Redefine Project Home and Project Page

e8d51d2

Add link to Dashboard in glossary term

23469de

Swap ads information to make it more relevant

92d2f3f

Restyle end of tutorial

aa7599d

Mention RTD tutorial in Getting Started with Sphinx guide

c4d450e

astrojuanlu enabled auto-merge August 24, 2021 15:45

astrojuanlu merged commit 0f15a96 into master Aug 24, 2021

astrojuanlu deleted the rtd-tutorial-part-i branch August 24, 2021 15:52

astrojuanlu mentioned this pull request Sep 7, 2021

New Read the Docs tutorial, part II #8473

Merged

astrojuanlu mentioned this pull request Oct 20, 2021

New Read the Docs tutorial, part III (and finale?) #8605

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New Read the Docs tutorial, part I #8428

New Read the Docs tutorial, part I #8428

astrojuanlu commented Aug 18, 2021 •

edited

astrojuanlu commented Aug 18, 2021

ericholscher left a comment

ericholscher Aug 18, 2021

ericholscher Aug 18, 2021

astrojuanlu Aug 19, 2021

astrojuanlu Aug 19, 2021

ericholscher Aug 18, 2021

astrojuanlu Aug 19, 2021

ericholscher Aug 18, 2021

astrojuanlu Aug 19, 2021 •

edited

ericholscher Aug 24, 2021

astrojuanlu commented Aug 19, 2021

astrojuanlu commented Aug 19, 2021

stsewd commented Aug 19, 2021

astrojuanlu commented Aug 19, 2021

ericholscher commented Aug 20, 2021

ericholscher left a comment

ericholscher Aug 24, 2021

astrojuanlu Aug 24, 2021

ericholscher Aug 24, 2021

ericholscher Aug 24, 2021

astrojuanlu Aug 24, 2021

		You can now proceed to make some basic configuration adjustments.
		For that, click on the "⚙ Admin" button, which will open the Settings page.

New Read the Docs tutorial, part I #8428

New Read the Docs tutorial, part I #8428

Conversation

astrojuanlu commented Aug 18, 2021 • edited

astrojuanlu commented Aug 18, 2021

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

astrojuanlu Aug 19, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

astrojuanlu commented Aug 19, 2021

astrojuanlu commented Aug 19, 2021

stsewd commented Aug 19, 2021

astrojuanlu commented Aug 19, 2021

ericholscher commented Aug 20, 2021

ericholscher left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

astrojuanlu commented Aug 18, 2021 •

edited

astrojuanlu Aug 19, 2021 •

edited