From b5d68b8ff15338d8b7e3ebfa8c406b1871d57e98 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 14 Jul 2016 10:13:10 +0100 Subject: [PATCH 1/2] Link to doc style doc (and update it to cover extra section characters) --- CONTRIBUTING.rst | 3 +++ meta/documentation_style.rst | 16 +++++++++++----- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 1cbba00b..f18263d0 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -87,6 +87,9 @@ matrix-doc should be based on the ``master`` branch.) Code style ~~~~~~~~~~ +The documentation style is described at +https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst. + Python code within the ``matrix-doc`` project should follow the same style as synapse, which is documented at https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst. diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 5cc5ce82..a6cfad51 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -19,11 +19,17 @@ RST support lots of different punctuation characters for underlines on sections. Content in the specification MUST use the same characters in order for the complete specification to be merged correctly. These characters are: -- ``=`` : Top-level sections -- ``-`` : Second-level sections -- ``~`` : Third-level sections -- ``+`` : Fourth-level sections -- You should rethink your document layout if you require a fifth level. +- ``=`` +- ``-`` +- ``~`` +- ``+`` +- ``^`` +- ````` +- ``@`` +- ``:`` + +If you find yourself using ``^`` or beyond, you should rethink your document +layout if possible. TODOs ----- From 0e26238386631cc1a171201018ce715e29cdbc22 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 14 Jul 2016 10:52:30 +0100 Subject: [PATCH 2/2] Update README Structure and Contributing were both a bit out of date. --- README.rst | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index f0da0267..76e3c1af 100644 --- a/README.rst +++ b/README.rst @@ -4,27 +4,36 @@ Structure ========= - ``api`` : Contains the HTTP API specification. -- ``drafts`` : Contains documents which will make it into the specification - and/or supporting documentation at some point in the future. -- ``event-schemas`` : Contains the `JSON Schema`_ for all Matrix events +- ``attic``: Contains historical sections of specification for reference + purposes. +- ``changelogs``: Contains change logs for the various parts of the + specification. +- ``drafts``: Previously, contained documents which were under discussion for + future incusion into the specification and/or supporting documentation. This + is now historical, as we use separate discussion documents (see + ``_). +- ``event-schemas``: Contains the `JSON Schema`_ for all Matrix events contained in the specification, along with example JSON files. -- ``meta`` : Contains documents outlining the processes involved when writing +- ``meta``: Contains documents outlining the processes involved when writing documents, e.g. documentation style, guidelines. -- ``scripts`` : Contains scripts to generate formatted versions of the +- ``scripts``: Contains scripts to generate formatted versions of the documentation, typically HTML. -- ``specification`` : Contains the specification split up into sections. -- ``supporting-docs`` : Contains additional documents which explain design +- ``specification``: Contains the specification split up into sections. +- ``supporting-docs``: Contains additional documents which explain design decisions, examples, use cases, etc. -- ``templating`` : Contains the templates and templating system used to +- ``templating``: Contains the templates and templating system used to generate the spec. Contributing ============ Known issues with the specification are represented as JIRA issues at -https://matrix.org/jira/browse/SPEC +``_. -If you want to ask more about the specification, or have suggestions for -improvements, join us on ``#matrix-dev:matrix.org`` via https://matrix.org/beta. +If you want to ask more about the specification, join us on +`#matrix-dev:matrix.org `_. + +If you would like to contribute to the specification or supporting +documentation, see ``_. .. _JSON Schema: http://json-schema.org/