diff mbox

[ovs-dev,1/6] doc: Add some useful tools for doc editing

Message ID 20161217222342.21653-1-stephen@that.guru
State Accepted
Headers show

Commit Message

Stephen Finucane Dec. 17, 2016, 10:23 p.m. UTC 
This has come up on the mailing list. Let's document it!

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 .../internals/contributing/documentation-style.rst | 29 +++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

Comments

Ben Pfaff Dec. 21, 2016, 9:40 p.m. UTC | #1 
On Sat, Dec 17, 2016 at 10:23:37PM +0000, Stephen Finucane wrote:
> This has come up on the mailing list. Let's document it!
> 
> Signed-off-by: Stephen Finucane <stephen@that.guru>

Thank you very much!  I applied this series to master.
diff mbox

Patch

diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst
index c32921e..02a8d50 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -35,12 +35,15 @@  documents found in the project tree.
 reStructuredText vs. Sphinx
 ---------------------------
 
-reStructuredText (reST) is the syntax, while Sphinx is a documentation
+`reStructuredText (reST)`__ is the syntax, while `Sphinx`__ is a documentation
 generator.  Sphinx introduces a number of extensions to reST, like the
 ``:ref:`` role, which can and should be used in documentation, but these will
 not work correctly on GitHub. As such, these extensions should not be used in
 any documentation in the root level, such as the ``README``.
 
+__ http://docutils.sourceforge.net/rst.html
+__ http://www.sphinx-doc.org/
+
 reST Conventions
 ----------------
 
@@ -324,9 +327,29 @@  vSwitch documentation. These guidelines are based on the `IBM Style Guide
 
   Avoid "please" and "thank you"
 
+Helpful Tools
+-------------
+
+There are a number of tools, online and offline, which can be used to preview
+documents are you edit them:
+
+- `rst.ninjs.org <http://rst.ninjs.org/>`__
+
+  An online rST editor/previewer
+
+- `ReText <https://github.com/retext-project/retext>`__
+
+  A simple but powerful editor for Markdown and reStructuredText. ReText is
+  written in Python.
+
+- `restview <https://mg.pov.lt/restview/>`__
+
+  A viewer for ReStructuredText documents that renders them on the fly.
+
 Useful Links
 ------------
 
-* `Quick reStructuredText
+- `Quick reStructuredText
   <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`__
-* `Sphinx Documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`__
+
+- `Sphinx Documentation <http://sphinx.readthedocs.org/en/latest/rest.html>`__