Skip to content

Commit

Permalink
Document the use of ... for :literal:...
Browse files Browse the repository at this point in the history
Requrested by @jwrober.
  • Loading branch information
lmoureaux committed Sep 12, 2021
1 parent b6a3aec commit 14d15d8
Showing 1 changed file with 21 additions and 21 deletions.
42 changes: 21 additions & 21 deletions docs/Developing/style-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Documentation Style Guide
.. role:: improvement
.. role:: wonder

The Longturn community uses the Python based Sphinx system to generate the documentation available on this
website and in the :file:`doc` directory in the released tarball. Sphinx takes plain text files formatted
with a superset of markdown called reStructuredText (ReST). Sphinx reStructuredText is documented here:
The Longturn community uses the Python based Sphinx system to generate the documentation available on this
website and in the :file:`doc` directory in the released tarball. Sphinx takes plain text files formatted
with a superset of markdown called reStructuredText (ReST). Sphinx reStructuredText is documented here:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

This style guide is mostly meant for documentation authors to ensure that we keep a consistent look and feel
Expand All @@ -19,7 +19,7 @@ Headings

Headings create chapter breaks between sections of a document as well as provide the title.

Heading 1
Heading 1
Heading 1 is used to for the title of the page/document. The asterisk is used to denote Heading 1 like
this:

Expand Down Expand Up @@ -53,31 +53,31 @@ Heading 3
Interpreted Text Roles
======================

Interpreted text roles are special code blocks that are inserted in line with regular text to create user
interface markup elements to bring attention to something or make it more obvious to the reader what you
want to do. Interpreted text roles are simply a code word surrounded by a colon on both sides and the text
Interpreted text roles are special code blocks that are inserted in line with regular text to create user
interface markup elements to bring attention to something or make it more obvious to the reader what you
want to do. Interpreted text roles are simply a code word surrounded by a colon on both sides and the text
you want to alter is placed inside back-ticks.

* :literal:`:doc:` -- Doc is used to create a hyperlink reference between documents in the documentation
* :literal:`:doc:` -- Doc is used to create a hyperlink reference between documents in the documentation
system.
* :literal:`:emphasis:` -- Emphasis is used to :emphasis:`bring attention to something`.
* :literal:`:file:` -- File is used for file names and paths such as :file:`~/.local/share/freeciv21/saves`
* :literal:`:guilabel:` -- GUI Label is used to bring attention to someting on the screen like the
* :literal:`:guilabel:` -- GUI Label is used to bring attention to someting on the screen like the
:guilabel:`Next` button on the installer wizard
* :literal:`:literal:` -- Literal is used when you want to note a text element in its raw form.
* :literal:`:menuselection:` -- Menu Selection is used to give the path of menu clicks such as
:menuselection:`Game --> Options --> Local Options`. To create the arrow character in between the options
* :literal:`:literal:` -- Literal is used when you want to note a text element in its raw form. This is equivalent to using four back-ticks: ````text````.
* :literal:`:menuselection:` -- Menu Selection is used to give the path of menu clicks such as
:menuselection:`Game --> Options --> Local Options`. To create the arrow character in between the options
you will place a text arrow like this: :literal:`-->` in between the selection items.
* :literal:`:strong:` -- Strong is used to :strong:`bold some text`.
* :literal:`:title-reference:` -- Title Reference is used notate a :title-reference:`title entry` in the
in-game help or to refer to a page in the documentation without giving an actual hyperlink reference
* :literal:`:title-reference:` -- Title Reference is used notate a :title-reference:`title entry` in the
in-game help or to refer to a page in the documentation without giving an actual hyperlink reference
(see :literal:`:doc:` above).

The docutils specification allows for custom Interpreted Text Roles and we use this feature. The docutils
documentation on this feature is available here:
documentation on this feature is available here:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles

* :literal:`:unit:` -- This provides an opportunity to highlight a Freeciv21 unit, such as the
* :literal:`:unit:` -- This provides an opportunity to highlight a Freeciv21 unit, such as the
:unit:`Musketeer`
* :literal:`:improvement:` -- This provides an opportunity to highlight a Freeciv21 building or city
improvement, such as the :improvement:`Granary`.
Expand All @@ -87,17 +87,17 @@ https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-
Admonition Directives
=====================

Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. Typically,
an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title
Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. Typically,
an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title
matching the admonition type. We use some of the standard admonitions in our documentation as well.

* :literal:`.. attention::` -- Use attention to bring a very important high profile item to the reader's
* :literal:`.. attention::` -- Use attention to bring a very important high profile item to the reader's
attention.

.. attention::
This is a really important message! Don't forget to eat breakfast every day.

* :literal:`.. todo::` -- Use To Do as a reminder for documentation editors to come back and fix things at
* :literal:`.. todo::` -- Use To Do as a reminder for documentation editors to come back and fix things at
a later date.

.. todo::
Expand All @@ -108,7 +108,7 @@ matching the admonition type. We use some of the standard admonitions in our doc
.. note::
It's important to note that Freeciv21 is really fun to play with group's of people online.

* :literal:`.. code-block:: rst` -- The code block is an excellent way to display actual code or any
* :literal:`.. code-block:: rst` -- The code block is an excellent way to display actual code or any
pre-formatted plain text.

.. code-block:: rst
Expand Down

0 comments on commit 14d15d8

Please sign in to comment.