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.

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 Sphinx tutorial, part II #9355

Merged
merged 31 commits into from Jul 6, 2021
Merged

Conversation

astrojuanlu
Copy link
Contributor

@astrojuanlu astrojuanlu commented Jun 16, 2021

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

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.

doc/tutorial/index.rst Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Show resolved Hide resolved
Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com>
@astrojuanlu
Copy link
Contributor Author

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

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!

doc/tutorial/index.rst Outdated Show resolved Hide resolved
Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Show resolved Hide resolved
doc/tutorial/index.rst Show resolved Hide resolved
astrojuanlu and others added 3 commits June 22, 2021 15:20
Co-authored-by: Jakob Lykke Andersen <jakobandersen@users.noreply.github.com>
@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!

doc/glossary.rst Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/usage/extensions/index.rst Outdated Show resolved Hide resolved
doc/usage/restructuredtext/directives.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
doc/tutorial/index.rst Outdated Show resolved Hide resolved
@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.

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!

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

.. 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
@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.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

7 participants