summaryrefslogtreecommitdiffstats
path: root/README.txt
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-10-31 23:37:45 -0700
committerChris Johns <chrisj@rtems.org>2016-11-01 18:23:23 +1100
commit4ace089bde87fa3a10fcd43d1291187406fcd23f (patch)
tree463063b9e3ca176a4dffa7eaae14dc82a3592d35 /README.txt
parentbb923d032f026fa3401dbda9183a128bdb9a70cd (diff)
downloadrtems-docs-4ace089bde87fa3a10fcd43d1291187406fcd23f.tar.bz2
Add some notes on writing documentation.
Diffstat (limited to 'README.txt')
-rw-r--r--README.txt130
1 files changed, 130 insertions, 0 deletions
diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..d70e715
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,130 @@
+RTEMS Project Documentation
+===========================
+
+The documents is written in ReST and built using Sphinx. The build system will
+check the version and ensure you have a suitable version. If your host does not
+provide a packaged version use PIP to fetch a recent version. The Sphinx
+website provides details on doing this.
+
+Building PDF requires a full Latex install.
+
+Building
+--------
+
+To build enter in the top directory:
+
+ $ ./waf configure
+ $ ./waf
+
+PDF output can be built without needing to configure again:
+
+ $ ./waf --pdf
+
+To build and install to a specific location:
+
+ $ ./waf configure --prefix=/foo/my/location
+ $ ./waf build install
+
+If you need to debug what is happening use configure with a suitable Sphinx
+version level:
+
+ $ ./waf configure --sphinx-verbose=-v
+ $ ./waf clean build
+
+Documentation Standard
+----------------------
+
+This following details the documentation standard. If in doubt first search the
+existing documentation for an example and if unsure ask.
+
+1. All text is to be formatted to wrap at 80 columns. Do not manually line feed
+ before 80.
+
+2. Pasted text such as console output can exceed 80 columns however it is
+ preferred even this text is wrapped at 80 columns. Long lines in code block
+ text causes issues with the PDF output.
+
+3. For pasted output, shell commands and code use '.. code-block::' with
+ 'c' for C code and 'shell' for shell code and terminal output. If you need
+ line number use:
+
+ .. code-block:: shell
+ :linenos:
+
+4. Use the directives for 'note', 'warning', and 'topic'. Do not add 'TIP',
+ 'Important' or 'Warning' to the text. Let the mark-up language handle
+ this. The supported directives are:
+
+ .. warning::
+ .. note::
+ .. topic::
+
+ These directives reference specific CSS sytle support.
+
+5. Images are placed in the 'images' directory. Do not place images in the
+ source directories. Using a common 'images' tree of images promotes sharing
+ of images. To add an image use:
+
+ .. figure:: ../images/my-image.png
+ :wdith: 75%
+ :align: center
+ :alt: This is the alt text for some output types.
+
+6. Callouts can be implement manually using a code block and a topic block. For
+ example:
+
+ .. code-block: c
+
+ #include <stdio.h> <1>
+ int main(int argc, char** argv) <2>
+ {
+ printf("Hello world\n"); <3>
+ return 0; <4>
+ }
+
+ .. topic:: Items:
+
+ 1. Include the standard input/output header file.
+
+ 2. The program starts here.
+
+ 3. Print something to the standard output device.
+
+ 4. Exit with an exit code of 0. This is value can be checked by the
+ caller of this program.
+
+ Note, the topic items are manually number. This makes is easier to see which
+ item matches the text. Use <> for the number and try to align to column
+ 76. If there is more than 9 items align to column 75. Use haning indents if
+ an items extends over a single line.
+
+7. Use the RTEMS domain references for URLs and mailing lists. For example to
+ insert the RTEMS developers list use:
+
+ :r:list:`devel`
+ :r:url:`git`
+
+ The valid lists are:
+
+ announce : Announce Mailing List
+ bugs : Bugs Mailing List
+ devel : Developers Mailing List
+ build : Build Logs
+ users : Users Mailing List
+ vc : Version Control Mailing List
+
+ The valif URLs are:
+
+ trac : https://devel.rtems.org/
+ devel : https://devel.rtems.org/
+ www : https://www.rtems.org/
+ buildbot : https://buildbot.rtems.org/
+ builder : https://builder.rtems.org/
+ docs : https://docs.rtems.org/
+ lists : https://lists.rtems.org/
+ git : https://git.rtems.org/
+ ftp : https://ftp.rtems.org/
+ review : https://review.rtems.org/
+ bugs : https://devel.rtems.org/wiki/Bugs/
+ gsoc : https://devel.rtems.org/wiki/GSoC/
+ socis : https://devel.rtems.org/wiki/SOCIS/