Skip to content
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.

Sign up for GitHub

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

Jump to bottom

New Sphinx tutorial, part II #9355

Merged
merged 31 commits into from
Jul 6, 2021
Merged

New Sphinx tutorial, part II #9355

merged 31 commits into from
Jul 6, 2021

Conversation

astrojuanlu
Copy link
Contributor

@astrojuanlu astrojuanlu commented Jun 16, 2021 •
edited
Loading

Feature or Bugfix

  • Feature

Purpose

This is a continuation of the tutorial we started at #9276. It expands some sections already started in the first part and adds some new ones, as originally proposed in #9165:

  1. First steps to document our project using Sphinx
  2. Customizing Sphinx configuration
  3. Writing narrative documentation with Sphinx

Again, the idea is to keep these pull requests manageable, iterate in small chunks, and in the meanwhile keep the tutorial in a complete state.

Rendered version: https://sphinx--9355.org.readthedocs.build/en/9355/tutorial/index.html

cc @ericholscher

Relates

@astrojuanlu astrojuanlu mentioned this pull request Jun 16, 2021
Closed
ericholscher
ericholscher reviewed Jun 17, 2021
View reviewed changes
Copy link
Contributor

@ericholscher ericholscher left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks great! Sorry for all the nitpicks, but mostly just trying to tweak small things.

@astrojuanlu astrojuanlu force-pushed the new-tutorial-part-ii branch from f956613 to 63678c6 Compare June 21, 2021 05:02
@astrojuanlu astrojuanlu force-pushed the new-tutorial-part-ii branch from 63678c6 to fb23605 Compare June 21, 2021 05:04
@astrojuanlu
Copy link
Contributor Author

Thank you @ericholscher for the thorough review! I have addressed your comments.

humitos
humitos approved these changes Jun 21, 2021
View reviewed changes
Copy link
Contributor

@humitos humitos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good progress on this!

@astrojuanlu @humitos
Update doc/tutorial/index.rst
a3478eb 
Co-authored-by: Manuel Kaufmann <[email protected]>
jakobandersen
jakobandersen requested changes Jun 22, 2021
View reviewed changes
@tk0miya
Copy link
Member

tk0miya commented Jul 3, 2021

Sorry, I did not have time to review this in recent weeks. I'll take time for this in this week. Please wait a moment. I think there is nothing to block your next work. Thank you for your great work!

tk0miya
tk0miya reviewed Jul 4, 2021
View reviewed changes
@astrojuanlu astrojuanlu force-pushed the new-tutorial-part-ii branch from 8a19a57 to cb846a3 Compare July 5, 2021 07:39
@astrojuanlu
Copy link
Contributor Author

Thanks folks for the extra round of reviews! I addressed all the comments. docslint is failing because there is a long URL that I don't know how to split, other than that this is ready I think.

@tk0miya tk0miya mentioned this pull request Jul 5, 2021
Merged
tk0miya
tk0miya reviewed Jul 5, 2021
View reviewed changes
Copy link
Member

@tk0miya tk0miya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@astrojuanlu astrojuanlu requested a review from jakobandersen July 5, 2021 18:15
jakobandersen
jakobandersen approved these changes Jul 5, 2021
View reviewed changes
Copy link
Contributor

@jakobandersen jakobandersen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@tk0miya tk0miya merged commit b2fa77c into sphinx-doc:4.x Jul 6, 2021
@tk0miya
Copy link
Member

tk0miya commented Jul 6, 2021

Just merged. Thank you for your great work!

@astrojuanlu astrojuanlu deleted the new-tutorial-part-ii branch July 6, 2021 13:43
@astrojuanlu
Copy link
Contributor Author

Thanks a lot @tk0miya! On to the next PR 💪🏽

@ericholscher
Copy link
Contributor

Excited to have this moving forward. Great work everyone. <3

@astrojuanlu astrojuanlu mentioned this pull request Jul 8, 2021
Closed
jfbu
jfbu reviewed Jul 19, 2021
View reviewed changes
doc/tutorial/index.rst
.. note::

Generating a PDF using Sphinx can be done running ``make latexpdf``,
provided that the system has a working :math:`\LaTeX` installation,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This breaks PDF production, as \(\LaTeX\) mark-up is invalid. \LaTeX can not be used in math mode.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Woops, sorry. Let's continue the conversation in #9475 and #9476

jfbu added a commit to jfbu/sphinx that referenced this pull request Jul 19, 2021
@jfbu
Remove mark-up breaking PDF output
e1612b4 
Close: sphinx-doc#9475

Refs: sphinx-doc#9355
@jfbu jfbu mentioned this pull request Jul 19, 2021
Merged
@astrojuanlu astrojuanlu mentioned this pull request Aug 9, 2021
Merged
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 19, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@ericholscher ericholscher ericholscher left review comments

@davidfischer davidfischer davidfischer left review comments

@jfbu jfbu jfbu left review comments

@humitos humitos humitos approved these changes

@tk0miya tk0miya tk0miya approved these changes

@jakobandersen jakobandersen jakobandersen approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@astrojuanlu @tk0miya @ericholscher @davidfischer @humitos @jfbu @jakobandersen