Skip to content

New Sphinx tutorial, part II#9355

Merged
tk0miya merged 31 commits intosphinx-doc:4.xfrom
astrojuanlu:new-tutorial-part-ii
Jul 6, 2021
Merged

New Sphinx tutorial, part II#9355
tk0miya merged 31 commits intosphinx-doc:4.xfrom
astrojuanlu:new-tutorial-part-ii

Conversation

@astrojuanlu
Copy link
Copy Markdown
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
davidfischer
davidfischer reviewed Jun 16, 2021
View reviewed changes
ericholscher
ericholscher reviewed Jun 17, 2021
View reviewed changes
Copy link
Copy Markdown
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
Copy Markdown
Contributor Author

astrojuanlu commented Jun 21, 2021

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
Copy Markdown
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
Copy Markdown
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
jakobandersen
jakobandersen 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
astrojuanlu commented Jul 5, 2021
View reviewed changes
@astrojuanlu
Copy link
Copy Markdown
Contributor Author

astrojuanlu commented Jul 5, 2021

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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
Contributor Author

astrojuanlu commented Jul 6, 2021

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

@ericholscher
Copy link
Copy Markdown
Contributor

ericholscher commented Jul 6, 2021

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
Copy Markdown
Contributor

@jfbu jfbu Jul 19, 2021

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
Copy Markdown
Contributor Author

@astrojuanlu astrojuanlu Jul 19, 2021

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

@jfbu jfbu jfbu left review comments

@tk0miya tk0miya tk0miya approved these changes

@jakobandersen jakobandersen jakobandersen approved these changes

+3 more reviewers

@ericholscher ericholscher ericholscher left review comments

@davidfischer davidfischer davidfischer left review comments

@humitos humitos humitos approved these changes

Reviewers whose approvals may not affect merge requirements

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