-- MikeGore - 2015-08-27

Automatic Documenation with SH2TWIKI

  • See ClusterTools for cluster setup * make docs will automatically extract BASH and C markups
  • Features
    • Uses half the markup required the doxygen
    • Understands SHELL Variables and Functions
  • Creates the TWIKI and HTML documenation from sources places them in:
    • /cscf-adm/src/twiki and /cscf-adm/src/html

sh2twiki markup rules

  • Heading: Markup syntax notes
  • Comments:
    • Comments start with // or #
    • Examples
    • # this is a comment
    • // this is a comment
  • Tokens:
    • Tokens are any word following a comment that ends with ':'
    • Examples
    • # Notes:
    • // Arguments: userid result
    • Notes: the token and any following comments are part of the token
  • Reserved:
    • The following tokens have special meaning
    • Title: Creates a title for the document.
    • This keyword and any unbroken chain of comments and unreserved
    • tokens are part of the title and will be listed in the index file.
    • Author: Document Author, also Authour works
    • Heading: Create a heading
  • Variables:
    • The following code objects have special meaning
    • VAR=value Variable assignments
    • This variable if following a token will become a comment
    • # ======== This a a section break
    • // ======= This is a section break
  • Blank_Lines:
    • Blank Comments lines end a token or grouping
    • Examples:
    • //
    • #
    • C enum are processed
    • enum {
    • value1,
    • value2
    • };
  • Functions: are processed along with the contents by counting brace levels
  • Note: ANY unbroken preceding group of tokens/comments are part of the
    • function documentation.
    • Functions names in the documentation are listed BEFORE the preceding tokens
  • Examples:
    • // This is a custom printf command
    • // Arguments: format string, variable number of arguments
    • // Returns: void
    • void myprintf(char *str, ...)
    • {
    • printf code goes here ...
    • }
  • Special_Keywords:
  • Processed keywords that create documentation sections
    • pause message
    • pause_yes message
    • pause_no message
    • must be followed by if,then,else,fo - optionly end with a section
    • Notes:
    • This is used in the ASIMOV updates script to create TWIKI documentation for
    • That script. The compatibility is included here

PXE

Topic revision: r2 - 2015-08-27 - MikeGore
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback