diff options
| author | Ben Kaduk <kaduk@mit.edu> | 2012-10-15 14:39:15 -0400 |
|---|---|---|
| committer | Ben Kaduk <kaduk@mit.edu> | 2012-10-15 19:20:44 -0400 |
| commit | e95f9f6875f4cbcae60fe96696eb83a6972bbf26 (patch) | |
| tree | a56a1baa43cb89187aaba76ab1eb8836511effed /doc/rst_source/README | |
| parent | ee26c4bbf4fc271ebf76d50a23ca27ef74220404 (diff) | |
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
Diffstat (limited to 'doc/rst_source/README')
| -rw-r--r-- | doc/rst_source/README | 69 |
1 files changed, 0 insertions, 69 deletions
diff --git a/doc/rst_source/README b/doc/rst_source/README deleted file mode 100644 index 8bb1c47cc..000000000 --- a/doc/rst_source/README +++ /dev/null @@ -1,69 +0,0 @@ -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. |
