Skip to content
This repository has been archived by the owner on Apr 26, 2024. It is now read-only.

Fixes to the formatting of README.rst #12627

Merged
merged 1 commit into from
May 4, 2022
Merged

Fixes to the formatting of README.rst #12627

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ solutions. The hope is for Matrix to act as the building blocks for a new
generation of fully open and interoperable messaging and VoIP apps for the
internet.

Synapse is a Matrix "homeserver" implementation developed by the matrix.org core
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I need to figure out how to configure PyCharm to not do this when it automatically wraps a line.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this trailing space was your doing, tbh, and it's not exactly the end of the world anyway. But my editor likes to strip them...

Synapse is a Matrix "homeserver" implementation developed by the matrix.org core
team, written in Python 3/Twisted.

In Matrix, every user runs one or more Matrix clients, which connect through to
Expand Down Expand Up @@ -294,13 +294,13 @@ directory of your choice::
cd synapse

Synapse has a number of external dependencies. We maintain a fixed development
environment using [poetry](https://python-poetry.org/). First, install poetry. We recommend
environment using `Poetry <https://python-poetry.org/>`_. First, install poetry. We recommend::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Arg. Is there a ReST linter that might have caught this? Maybe https://pypi.org/project/restructuredtext-lint/

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, my training/tradition is to treat displayed items as a noun in the flow of a sentence, including punctuation if ending the sentence. Though this doesn't work brilliantly for source code.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Arg. Is there a ReST linter that might have caught this? Maybe https://pypi.org/project/restructuredtext-lint/

I've never looked into this, tbh. Given the README is the only RST thing we have nowadays, I'm not sure it's worth much linting effort, though I'll not statnd in the way.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, my training/tradition is to treat displayed items as a noun in the flow of a sentence, including punctuation if ending the sentence. Though this doesn't work brilliantly for source code.

Afraid I'm not really sure what you're referring to here. The capitalisation of "Poetry"? The :: ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've never looked into this, tbh. Given the README is the only RST thing we have nowadays, I'm not sure it's worth much linting effort, though I'll not statnd in the way.

Further, it's not obvious what there is to "catch": it was valid RST, it just didn't do what you wanted it to do. markdown-style links are a common error that we could look for explicitly, I suppose, but I'm not sure it's reasonable to expect any generic RST linter to do so.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, my training/tradition is to treat displayed items as a noun in the flow of a sentence, including punctuation if ending the sentence. Though this doesn't work brilliantly for source code.

Afraid I'm not really sure what you're referring to here. The capitalisation of "Poetry"? The :: ?

Sorry. I meant the omission of the trailing ::. The intent was that the following is all one sentence:

We recommend <block of shell>, as described here.

But that's a mionr style thing that isn't worth squabbling over.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want a program that knows all of the mistakes that I make in advance and catches them. AKA, the moon on a stick.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry. I meant the omission of the trailing ::. The intent was that the following is all one sentence:

Oh right. :: in RST has special syntactic meaning (https://docutils.sourceforge.io/docs/user/rst/quickref.html#literal-blocks). Not sure if there is a way to get that effect without also getting a : in the output.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if there is a way to get that effect without also getting a : in the output.

apparently you stick the :: on a line on its own. TIL.


| pip install --user pipx
| pipx install poetry
pip install --user pipx
pipx install poetry

as described `here <https://python-poetry.org/docs/#installing-with-pipx>`_.
(See `poetry's installation docs <https://python-poetry.org/docs/#installation>`
(See `poetry's installation docs <https://python-poetry.org/docs/#installation>`_
for other installation methods.) Then ask poetry to create a virtual environment
from the project and install Synapse's dependencies::

Expand All @@ -309,11 +309,11 @@ from the project and install Synapse's dependencies::
This will run a process of downloading and installing all the needed
dependencies into a virtual env.

We recommend using the demo which starts 3 federated instances running on ports `8080` - `8082`
We recommend using the demo which starts 3 federated instances running on ports `8080` - `8082`::

poetry run ./demo/start.sh

(to stop, you can use `poetry run ./demo/stop.sh`)
(to stop, you can use ``poetry run ./demo/stop.sh``)

See the `demo documentation <https://matrix-org.github.io/synapse/develop/development/demo.html>`_
for more information.
Expand Down
1 change: 1 addition & 0 deletions changelog.d/12627.doc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Fixes to the formatting of README.rst.