diff options
| author | Stephen Finucane <stephen@that.guru> | 2016-12-17 22:23:37 +0000 |
|---|---|---|
| committer | Ben Pfaff <blp@ovn.org> | 2016-12-21 13:38:42 -0800 |
| commit | 945535044eedbbe913949d32cf6ba43463af507b (patch) | |
| tree | d05dbd1945933b6c7d978543eba4724b7a3e9117 /Documentation/internals | |
| parent | 93d379fc6dafd18e7ed5f684fd91df9e8db14edb (diff) | |
| download | openvswitch-945535044eedbbe913949d32cf6ba43463af507b.tar.gz | |
doc: Add some useful tools for doc editing
This has come up on the mailing list. Let's document it!
Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>
Diffstat (limited to 'Documentation/internals')
| -rw-r--r-- | Documentation/internals/contributing/documentation-style.rst | 29 |
1 files changed, 26 insertions, 3 deletions
diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst index 318cc81ef..a3149ba6d 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 ---------------- @@ -325,9 +328,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>`__ |