Massive reST content rename

All of rst_source/ is now just in doc/.
The krb_ prefix is stripped from the document sub-directories.
rst_tools are now just tools.

The section headers of kadmind, krb5kdc, and sserver match as conflict markers.
bigredbutton: whitespace

ticket: 7409

1 files changed, 69 insertions, 0 deletions

diff --git a/doc/README b/doc/README
new file mode 100644
index 000000000..8bb1c47cc
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,69 @@
+HTML
+====
+
+To build the documentation as HTML pages run:
+
+sphinx-build source_dir  destination_dir
+
+where
+source_dir is the source directory which includes configuration file conf.py and all source files;
+destination_dir is the directory for the built documentation.
+
+Once completed, the newly generated HTML documentation can be viewed from the browser by pointing to destination_dir/index.html
+
+
+MAN PAGES
+=========
+
+Similarly, to build the documentation as man pages run:
+
+sphinx-build -b man source_dir  destination_dir
+
+The list of manual pages to be built should be constructed under man_pages section on conf.py
+
+
+CONVENTIONS
+===========
+
+We use the following conventions:
+
+* Use four-space indentation where indentation levels are arbitrary.
+  Do not use tabs anywhere.  Avoid trailing whitespace at the end of
+  lines or files.
+
+* Fill lines to 70 columns (the emacs default) where lines can be
+  wrapped.
+
+* For section headers, use === underlines for page titles, --- for
+  sections, ~~~ for subsections, and ### for sub-subsections.  Make
+  underlines exactly as long as titles.  Do not include trailing
+  punctuation in section headers.  Do not capitalize section headers
+  (except for the first word) except in source files intended to
+  generate man pages.
+
+* For bullet lists, use * for top-level bullets and - for sub-bullets.
+  Do not indent bullet or enumerated lists relative to the surrounding
+  text.
+
+* Use italics (*word*) for words representing variables or parameters.
+  Use boldface (**word**) for command options, subcommands of programs
+  like kadmin, and krb5.conf/kdc.conf parameter names.  Use literal
+  text (``text``) for examples and multi-component pathnames.  For
+  command names, single-component filenames, and krb5.conf/kdc.conf
+  section names, use references (like :ref:`kadmin(1)`) if introducing
+  them, or just use them unadorned otherwise.
+
+* In man pages for commands with subcommands, make a subsection for
+  each subcommand.  Start the subcommand with an indented synopsis,
+  then follow with non-indented text describing the subcommand and its
+  options.  See kadmin_local.rst for an example.
+
+* In man page synopses, put a newline in the RST source before each
+  option.  Put all parts of the synopsis at the same indentation
+  level.  Ideally we would want a hanging indent to the width of the
+  command or subcommand name, but RST doesn't support that.  Use
+  boldface for literal text in the synopsis, italics for variable
+  text, and unadorned text for syntax symbols (such as square brackets
+  to indicate optional parameters).  If immediately following one kind
+  of inline markup with another or putting inline markup next to
+  punctuation, you may need to use "\ " as a dummy separator.