FC-0068 docs: update quick reference RST content #613
Conversation
This PR adds the references from the past Templates page to the quick reference RST page to avoid losing import information while adding the new content.
openedx-webhooks
added
the
open-source-contribution
|
Thanks for the pull request, @Apgomeznext! What's next?Please work through the following steps to get your changes ready for engineering review: 🔘 Get product approvalIf you haven't already, check this list to see if your contribution needs to go through the product review process.
🔘 Provide contextTo help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:
🔘 Get a green buildIf one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green. 🔘 Let us know that your PR is ready for review:Who will review my changes?This repository is currently maintained by Where can I find more information?If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:
When can I expect my changes to be merged?Our goal is to get community contributions seen and reviewed as efficiently as possible. However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:
💡 As a result it may take up to several weeks or months to complete a review and merge your PR. |
| @@ -19,6 +19,55 @@ Headings | |||
|
|
|||
| RST allows you to use almost any symbol to underline headings, as long as you're consistent between heading level. However, the way shown above is how headings should be defined in all Open edX documentation. | |||
|
|
|||
| Develop Sections | |||
There was a problem hiding this comment.
| Develop Sections | |
| How To Use Sections Effectively |
|
|
||
| You can nest sections in the topic as needed, to give it structure and break it up into discrete parts. | ||
|
|
||
| Copy the Topic and Section Structure as needed |
There was a problem hiding this comment.
| Copy the Topic and Section Structure as needed | |
| Copy the Topic and Section Structure below as needed. |
| If this is a long topic with multiple sections, use the **contents** directive below: | ||
|
|
||
| .. contents:: Contents | ||
| :local: |
There was a problem hiding this comment.
This is indented wrong I think, the : needs to be two spaces in from the above ... I'd also add the :depth: parameter.
.. contents::
:depth: 1
:local:
| @@ -172,6 +221,111 @@ Use the following code: | |||
|
|
|||
| .. seealso:: To see alternative ways of defining tables, visit the `RST documentation about this topic <https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#tables>`_. | |||
|
|
|||
| Add a Substitution | |||
There was a problem hiding this comment.
I think this section is more confusing than helpful. I've never used this - do we use it a lot?
There was a problem hiding this comment.
I have never used it either. I added it because it was on the previous template page, and I wanted to include all the content in case it was necessary.
If you agree, I will erase it for the final version.
| Add a Sidebar | ||
| ************* | ||
|
|
||
| You can add any content in a sidebar. Open edX uses sidebars for image thumbnails, videos, and other notes. |
There was a problem hiding this comment.
| You can add any content in a sidebar. Open edX uses sidebars for image thumbnails, videos, and other notes. | |
| You can add any content in a sidebar. Open edX documentation uses sidebars for image thumbnails, videos, and other notes. |
Use Open edX as an adjective. Also, the site already has sidebars, should we be encouraging use of more?
There was a problem hiding this comment.
It is the same case as the substitution. I added it here to keep all the information on the previous template page. Still, I agree with you that adding more sidebars to the repository can be excessive, as we already have it. However, in the case of parallel repositories like the one for Aspects, it could be helpful to have different tools and references.
I have also seen these sidebars used in glossaries. I vote to keep it.
|
|
||
| A line of text with an |variable name| inserted. | ||
|
|
||
| Add an Thumbnail in a Sidebar |
There was a problem hiding this comment.
| Add an Thumbnail in a Sidebar | |
| Add a Thumbnail in a Sidebar |
|
|
||
| .. thumbnail:: _images/image-file-name | ||
|
|
||
| Use Inline Formatting |
There was a problem hiding this comment.
This section is identical to the above https://docsopenedxorg--613.org.readthedocs.build/en/613/documentors/references/quick_reference_rst.html#inline-markup section, so this can be removed.
This PR solves Sarina's change request.
This PR adds the references from the past Templates page to the quick reference RST page to avoid losing import information while adding the new content.