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. * For directives that take a content block (e.g., note, error, and warning), leave a blank line before the content block (after any arguments or options that may be present).