-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New Read the Docs tutorial, part I #8428
Changes from 10 commits
b91563f
4955c53
afb9681
cb86de4
35a188f
8720d09
85f533f
41a48fe
06860b2
0626dac
b2a8346
2328b35
e8d51d2
23469de
92d2f3f
aa7599d
c4d450e
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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: | ||
# This error needs to be ignored for now | ||
# See: https://github.com/myint/rstcheck/issues/19 | ||
ignore_messages=(Hyperlink target ".*" is not referenced) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
Glossary | ||
======== | ||
|
||
.. glossary:: | ||
|
||
dashboard | ||
Main page where you can see all your projects with their build status | ||
and import a new project. | ||
astrojuanlu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
profile page | ||
Page where you can see the projects of a certain user. | ||
|
||
project home | ||
astrojuanlu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
The main section of the :term:`project page`, where you can see the active versions, | ||
the description, and other basic project metadata (repository URL, maintainers, home, tags, ...). | ||
|
||
project page | ||
Page where you can access all the features of Read the Docs, | ||
from having an overview in the :term:`project home` to browsing the latest builds | ||
or administering your project. |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -25,21 +25,14 @@ Preparing your project on GitHub | |
|
||
To start, `sign in to GitHub <https://github.com/login>`_ | ||
and navigate to `the tutorial GitHub template <https://github.com/astrojuanlu/tutorial-template/>`_, | ||
where you will see a green "Use this template" button. | ||
where you will see a green :guilabel:`Use this template` button. | ||
Click it to open a new page that will ask you for some details: | ||
|
||
* Leave the default "Owner", or optionally change it if you desire. | ||
* Leave the default "Owner", or change it to something better for a tutorial project. | ||
* Introduce an appropriate "Repository name", for example ``rtd-tutorial``. | ||
* Make sure the project is "Public", rather than "Private". | ||
|
||
.. figure:: /_static/images/tutorial/github-template.png | ||
:width: 80% | ||
:align: center | ||
:alt: GitHub template for the tutorial | ||
|
||
GitHub template for the tutorial | ||
|
||
After that, click on the green "Create repository from template" button, | ||
After that, click on the green :guilabel:`Create repository from template` button, | ||
which will generate a new repository on your personal account | ||
(or the one of your choosing). | ||
This is the repository you will import on Read the Docs, | ||
|
@@ -61,13 +54,20 @@ and it contains the following files: | |
the Sphinx configuration ``docs/source/conf.py``, | ||
and the root document ``docs/source/index.rst`` written in reStructuredText. | ||
|
||
.. figure:: /_static/images/tutorial/github-template.png | ||
:width: 80% | ||
:align: center | ||
:alt: GitHub template for the tutorial | ||
|
||
GitHub template for the tutorial | ||
|
||
Sign up for Read the Docs | ||
~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To sign up for a Read the Docs account, | ||
navigate to the `Sign Up page <https://readthedocs.org/accounts/signup/>`_ | ||
and choose the option "Sign up with GitHub". | ||
On the authorization page, click the green "Authorize readthedocs" button. | ||
and choose the option :guilabel:`Sign up with GitHub`. | ||
On the authorization page, click the green :guilabel:`Authorize readthedocs` button. | ||
|
||
.. figure:: /_static/images/tutorial/github-authorization.png | ||
:width: 60% | ||
|
@@ -86,8 +86,8 @@ On the authorization page, click the green "Authorize readthedocs" button. | |
|
||
After that, you will be redirected to Read the Docs, | ||
where you will need to confirm your e-mail and username. | ||
Clicking the "Sign Up »" button will create your account | ||
and redirect you to your *dashboard*. | ||
Clicking the :guilabel:`Sign Up »` button will create your account | ||
and redirect you to your :term:`dashboard`. | ||
|
||
By now, you should have two email notifications: | ||
|
||
|
@@ -122,22 +122,22 @@ Importing the project to Read the Docs | |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
To import your GitHub project to Read the Docs, | ||
first click on the "Import a Project" button on your dashboard | ||
first click on the :guilabel:`Import a Project` button on your dashboard | ||
(or browse to `the import page <https://readthedocs.org/dashboard/import/>`_ directly). | ||
You should see your GitHub account under the "Filter repositories" list on the right. | ||
If the list of repositories is empty, click the "refreshing your accounts" link, | ||
If the list of repositories is empty, click the |:arrows_counterclockwise:| button, | ||
and after that all your repositories will appear on the center. | ||
|
||
.. figure:: /_static/images/tutorial/rtd-import-projects.png | ||
.. figure:: /_static/images/tutorial/rtd-import-projects.gif | ||
:width: 80% | ||
:align: center | ||
:alt: Import projects view | ||
:alt: Import projects workflow | ||
|
||
Import projects view | ||
Import projects workflow | ||
|
||
Locate your ``rtd-tutorial`` project | ||
(possibly clicking "next ››" at the bottom if you have several pages of projects), | ||
and then click on the "+" button to the right of the name. | ||
(possibly clicking :guilabel:`next ››` at the bottom if you have several pages of projects), | ||
and then click on the |:heavy_plus_sign:| button to the right of the name. | ||
The next page will ask you to fill some details about your Read the Docs project: | ||
|
||
Name | ||
|
@@ -149,16 +149,16 @@ Repository URL | |
The URL that contains the sources. Leave the automatically filled value. | ||
|
||
Repository type | ||
Version control system used, leave it to "Git" (which should be the default). | ||
Version control system used, leave it as "Git". | ||
|
||
Default branch | ||
Name of the default branch of the project, leave it to ``main``. | ||
Name of the default branch of the project, leave it as ``main``. | ||
|
||
Edit advanced project options | ||
Leave it unchecked, we will make some changes later. | ||
|
||
After hitting the "Next" button, you will be redirected to the project home. | ||
You just created your first project on Read the Docs! | ||
After hitting the :guilabel:`Next` button, you will be redirected to the :term:`project home`. | ||
You just created your first project on Read the Docs! |:tada:| | ||
|
||
.. figure:: /_static/images/tutorial/rtd-project-home.png | ||
:width: 80% | ||
|
@@ -173,7 +173,7 @@ Checking the first build | |
Read the Docs will try to build the documentation of your project | ||
right after you create it. | ||
To see the build logs, | ||
click on the "Your documentation is building" link on the dashboard, | ||
click on the "Your documentation is building" link on the project home, | ||
astrojuanlu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
or alternatively navigate to the "Builds" page, | ||
then open the one on top (the most recent one). | ||
|
||
|
@@ -200,11 +200,24 @@ If you now click on "View docs", you will see your documentation live! | |
|
||
HTML documentation live on Read the Docs | ||
|
||
.. note:: | ||
|
||
If you don't see the ad, you might be using an ad blocker. | ||
Our Ethical Ads network respects your privacy, doesn't target you, | ||
and tries to be as unobstrusive as possible, | ||
so we would like to kindly ask you to :doc:`not block us </advertising/ad-blocking>` |:heart:| | ||
|
||
Advertisement is one of our main sources of revenue. | ||
astrojuanlu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
If you want to learn more about how do we fund our operations | ||
and explore options to go ad-free, | ||
check out our `Sustainability page <https://readthedocs.org/sustainability/>`_. | ||
|
||
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` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 💯 |
||
and click on the "⚙ Admin" button, which will open the Settings page. | ||
|
||
First of all, add the following text in the description: | ||
|
||
|
@@ -229,10 +242,10 @@ and gives you a preview of how the documentation would look like with those chan | |
|
||
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. | ||
and click the :guilabel:`Save` button at the bottom of the page. | ||
|
||
Next, navigate to your GitHub repository, locate the file ``docs/source/index.rst``, | ||
and click on the pencil icon on the top-right with the tooltip "Edit this file" | ||
and click on the |:pencil2:| icon on the top-right with the tooltip "Edit this file" | ||
to open a web editor (more information `on their documentation`__). | ||
|
||
__ https://docs.github.com/en/github/managing-files-in-a-repository/managing-files-on-github/editing-files-in-your-repository | ||
|
@@ -250,10 +263,10 @@ In the editor, add the following sentence to the file: | |
|
||
Write an appropriate commit message, | ||
and choose the "Create a **new branch** for this commit and start a pull request" option, | ||
typing a sensible name for the new branch. | ||
When you are done, click the green "Propose changes" button, | ||
typing a name for the new branch. | ||
When you are done, click the green :guilabel:`Propose changes` button, | ||
which will take you to the new pull request page, | ||
and there click the "Create pull request" button below the description. | ||
and there click the :guilabel:`Create pull request` button below the description. | ||
|
||
.. figure:: /_static/images/tutorial/gh-pr-build.png | ||
:width: 80% | ||
|
@@ -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! | ||
astrojuanlu marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
That's the end of the tutorial for now, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Let's just remove it? |
||
but you can learn more about the platform starting with our :doc:`/features` page. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would be nice if we could just say ignore
:*:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That won't work apparently https://github.com/myint/rstcheck/blob/3f92957478422df87bd730abde66f089cc1ee19b/rstcheck.py#L265-L266 and rstcheck seems to be unmaintained.