GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Add a quick reference for rst markup. by ezio-melotti · Pull Request #916 · python/devguide

Conversation

@ezio-melotti

@ezio-melotti ezio-melotti commented Jul 13, 2022

Copy link
Copy Markdown
Member

This PR adds a quick reference table at the top of the rst reference page. The goal of this table is to show some commonly used markup and to include links to the relevant sections. I also added some internal references and changed a title.

This was proposed a decade ago on IRC, and then captured in python/cpython#58426 (comment) 1

Footnotes

  1. note that the issue itself (now transferred to include rendered output in addition to markup #14) is probably obsolete, and this proposal doesn't aim to solve that. ↩

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
erlend-aasland reacted with thumbs up emoji
All reactions
  • 👍 1 reaction
@ezio-melotti
Add a quick reference for rst markup.
fe334f7
@ezio-melotti ezio-melotti added the type-feature Additions; New content or section needed label Jul 13, 2022
@ezio-melotti ezio-melotti self-assigned this Jul 13, 2022
ezio-melotti
ezio-melotti commented Jul 13, 2022
View reviewed changes
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ezio-melotti ezio-melotti mentioned this pull request Jul 31, 2022
gh-94635: Add Reference, How-to, and Concepts headings to sqlite3 docs python/cpython#94636
Merged
CAM-Gerlach
CAM-Gerlach reviewed Jul 31, 2022
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member

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.

IMO, this PR is definitely a great improvement from a reader quick-reference perspective.

I do think, like for PEP 12, we shouldn't duplicate the Sphinx reST primer nearly word for word in most places, as opposed to just linking to it (via Intersphinx) and focusing on the guidance and conventions unique and specific to the CPython docs. I've opened python/docs-community#57 to discuss that issue further.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ezio-melotti
Address review comments.
38af603
@ezio-melotti

ezio-melotti commented Aug 2, 2022

Copy link
Copy Markdown
Member Author

Here is a new iteration:
image

  • added parameters next to arguments
  • merged vars/literals/code
  • added examples of roles with custom text, without links, without the first part1.

I didn't add methods/classes as discussed in a previous comment. The goal of this table is to provide a quick reminder for the syntax (e.g. how do I create a link? or a coment? was it .. directive: or .. directive::?) -- additional roles (like meth or class) are just a click away.

Footnotes

  1. the descriptions in the first column are not too accurate, but IMHO functional enough. People that already know that e.g. there's a way to only show the last component of an object will recognize the entry and see the syntax in the table; people that are not familiar with the feature or find the description confusing can always click the link and find a more exhaustive description. ↩
CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 1 reaction

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
CAM-Gerlach
CAM-Gerlach reviewed Aug 3, 2022
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

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.

Looks good overall with your changes 👍 , I just had some textual improvements, minor nits and bikeshedding

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@CAM-Gerlach CAM-Gerlach mentioned this pull request Aug 3, 2022
Clarify best practices with ref target labels in docs #927
Open
@ezio-melotti
Address review comments.
fe73d05
@ezio-melotti

ezio-melotti commented Aug 4, 2022 •
edited
Loading

Uh oh!

There was an error while loading. Please reload this page.

Copy link
Copy Markdown
Member Author

I believe I addressed all comments. This is the latest iteration of the table:
image

I also had to use a couple of rst tricks for .. and ``...``, but I was able to get it to work using :literal:`...`:
image
image
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
CAM-Gerlach
CAM-Gerlach reviewed Aug 4, 2022
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

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.

I suggested some re-writes to the roles section to avoid parts that are contradictory, duplicative and potentially confusing. Otherwise, this looks pretty good overall.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
CAM-Gerlach
CAM-Gerlach reviewed Aug 4, 2022
View reviewed changes
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ezio-melotti @CAM-Gerlach
Address review comments.
5b35d54 
Co-authored-by: CAM Gerlach <[email protected]>
CAM-Gerlach
CAM-Gerlach approved these changes Aug 5, 2022
View reviewed changes

@CAM-Gerlach CAM-Gerlach left a comment

Copy link
Copy Markdown
Member

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.

Two tiny tweaks, otherwise LGTM 👍

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
All reactions
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
Comment thread documentation/markup.rst Resolved

Uh oh!

There was an error while loading. Please reload this page.
@ezio-melotti @CAM-Gerlach
Apply suggestions from code review.
c39d593 
Co-authored-by: CAM Gerlach <[email protected]>
@ezio-melotti
ezio-melotti merged commit e807042 into python:main Aug 6, 2022
@ezio-melotti
ezio-melotti deleted the rst-quick-ref branch August 6, 2022 00:01
@ezio-melotti

ezio-melotti commented Aug 6, 2022

Copy link
Copy Markdown
Member Author

Merged. thanks for the review and suggestions!
All reactions

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.
@CAM-Gerlach CAM-Gerlach mentioned this pull request Dec 6, 2022
reST Primer duplicates the Sphinx version; should link to it instead #1000
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@erlend-aasland erlend-aasland erlend-aasland left review comments
@CAM-Gerlach CAM-Gerlach CAM-Gerlach approved these changes

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@ezio-melotti ezio-melotti

Labels

type-feature Additions; New content or section needed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@ezio-melotti @erlend-aasland @CAM-Gerlach
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.