From f34127b0260f6a572df3398bf796162564430923 Mon Sep 17 00:00:00 2001 From: Victor Hu Date: Fri, 23 Oct 2015 20:42:06 -0400 Subject: [PATCH] Rearranged the developers area to group topics together Added documentation primarily for building the man pages locally There is a requirement for pod2rst Modified the create_man_pages script to allow for local perl module path --- create_man_pages.py | 49 +++- docs/source/developers/debug_xcat.rst | 2 - docs/source/developers/developer_guide.rst | 2 - docs/source/developers/guides/code/builds.rst | 57 ++++ docs/source/developers/guides/code/debug.rst | 2 + docs/source/developers/guides/code/index.rst | 9 + docs/source/developers/guides/code/tips.rst | 2 + .../developers/guides/docs/doc_guidelines.rst | 255 ++++++++++++++++++ docs/source/developers/guides/docs/index.rst | 7 + docs/source/developers/guides/index.rst | 8 + docs/source/developers/index.rst | 5 +- docs/source/developers/programming_tips.rst | 2 - 12 files changed, 385 insertions(+), 15 deletions(-) delete mode 100644 docs/source/developers/debug_xcat.rst delete mode 100644 docs/source/developers/developer_guide.rst create mode 100644 docs/source/developers/guides/code/builds.rst create mode 100644 docs/source/developers/guides/code/debug.rst create mode 100644 docs/source/developers/guides/code/index.rst create mode 100644 docs/source/developers/guides/code/tips.rst create mode 100644 docs/source/developers/guides/docs/doc_guidelines.rst create mode 100644 docs/source/developers/guides/docs/index.rst create mode 100644 docs/source/developers/guides/index.rst delete mode 100644 docs/source/developers/programming_tips.rst diff --git a/create_man_pages.py b/create_man_pages.py index ee7ca06b6..c4b38cc43 100755 --- a/create_man_pages.py +++ b/create_man_pages.py @@ -1,19 +1,54 @@ #!/usr/bin/env python +#TODO: Delete the old files to support removing a man page import glob import os import sys import subprocess -#TODO: Delete the old files to support removing a man page +from optparse import OptionParser + +usage = "usage: %prog [options]" + +parser = OptionParser(usage=usage) +parser.add_option("--prefix", dest="PREFIX", help="Specify the location of the Perl modules") + +(options, args) = parser.parse_args() + +POD2RST="pod2rst" def cmd_exists(cmd): return subprocess.call("type " + cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE) == 0 -if not cmd_exists("pod2rst"): - print "ERROR, %s requires pod2rst to continue!" %(os.path.basename(__file__)) - sys.exit(1) +prefix_path = None +prefix_lib_path = None + +if options.PREFIX: + if '~' in options.PREFIX: + # else assume full path is provided + prefix_path = os.path.expanduser(options.PREFIX) + else: + prefix_path = options.PREFIX + + if not cmd_exists("%s/bin/pod2rst" %(prefix_path)): + print "ERROR, %s requires pod2rst, not found in %s/bin/" %(os.path.basename(__file__), prefix_path) + parser.print_help() + sys.exit(1) + + prefix_lib_path = "%s/lib" %(prefix_path) + if not os.path.isdir(prefix_lib_path): + prefix_lib_path = "%s/lib64" %(prefix_path) + if not os.path.isdir(prefix_lib_path): + print "ERROR, Cannot find the Perl lib directory in %s/lib or %s/lib64" %(prefix_path, prefix_path) + sys.exit(1) + +else: + if not cmd_exists(POD2RST): + print "ERROR, %s requires pod2rst to continue!" %(os.path.basename(__file__)) + parser.print_help() + sys.exit(1) + # the location relativate to xcat-core where the man pages will go MANPAGE_DEST="./docs/source/guides/admin-guides/references/man" @@ -53,6 +88,10 @@ for component in COMPONENTS: rst_output = "%s/%s" %(DESTINATION, outputFile) # generate the pod2rst command - cmd = "pod2rst --infile=%s --outfile=%s --title=%s.%s" %(pod_input, rst_output, title, man_ver) + cmd = "%s" %(POD2RST) + if options.PREFIX: + cmd = "perl -I %s/share/perl5 %s/bin/%s " %(prefix_path, prefix_path, POD2RST) + + cmd += " --infile=%s --outfile=%s --title=%s.%s" %(pod_input, rst_output, title, man_ver) print cmd os.system(cmd) diff --git a/docs/source/developers/debug_xcat.rst b/docs/source/developers/debug_xcat.rst deleted file mode 100644 index 7ae5bab53..000000000 --- a/docs/source/developers/debug_xcat.rst +++ /dev/null @@ -1,2 +0,0 @@ -Debug xCAT Problems -=================== diff --git a/docs/source/developers/developer_guide.rst b/docs/source/developers/developer_guide.rst deleted file mode 100644 index cf18c40ac..000000000 --- a/docs/source/developers/developer_guide.rst +++ /dev/null @@ -1,2 +0,0 @@ -Developer Guide -=============== diff --git a/docs/source/developers/guides/code/builds.rst b/docs/source/developers/guides/code/builds.rst new file mode 100644 index 000000000..9d46e9b65 --- /dev/null +++ b/docs/source/developers/guides/code/builds.rst @@ -0,0 +1,57 @@ +Building Source Code +==================== + +xcat-core +--------- + +Clone the xCAT project from `GitHub `_:: + + cd xcat-core + ./buildcore.sh + +xcat-deps +--------- + +The ``xcat-deps`` package is currently owned and maintained by the core development on our internal servers. Please use the packages created at: http://xcat.org/download.html#xcat-dep + + +man pages +--------- + +The xCAT man pages are written in Perl POD files and automatically get built into the xCAT rpms. The content in the .pod files are always the master. + +In the past, the man pages were converted into html files and uploaded to SourceForge. In moving to `ReadTheDocs `_ we want to also provide the man pages as references in the documentation. To convert the ``pods`` to ``rst``, we are using The Perl module: `pod2rst `_. + +The following steps will help configure ``pod2rst`` and be able to generate the changes .rst files to push to GitHub. + +#. Download the following Perl modules: + + - `Pod-POM-View-Restructured-0.02 `_ + - `Pod-POM-2.00 `_ + +#. For each of the above Perl modules: + + * **[root]** Extract and build the Perl module :: + + perl Makefile.PL + make + make install + + * **[non-root]** Extrat and build the Perl module using PREFIX to specify a directory that you have write permission :: + + mkdir ~/perllib + perl Makefile.PL PREFIX=~/perllib + make + make install + +#. Execute the script ``create_man_pages.py`` to generate the .rst files into ``xcat-core/docs`` : + + * **[root]** :: + + cd xcat-core + ./create_man_pages.py + + * **[non root]** :: + + cd xcat-core + ./create_man_pages.py --prefix=~/perllib diff --git a/docs/source/developers/guides/code/debug.rst b/docs/source/developers/guides/code/debug.rst new file mode 100644 index 000000000..d041fcea9 --- /dev/null +++ b/docs/source/developers/guides/code/debug.rst @@ -0,0 +1,2 @@ +Debug Problems +============== diff --git a/docs/source/developers/guides/code/index.rst b/docs/source/developers/guides/code/index.rst new file mode 100644 index 000000000..0447e3fb7 --- /dev/null +++ b/docs/source/developers/guides/code/index.rst @@ -0,0 +1,9 @@ +Code Development +================ + +.. toctree:: + :maxdepth: 2 + + builds.rst + debug.rst + tips.rst diff --git a/docs/source/developers/guides/code/tips.rst b/docs/source/developers/guides/code/tips.rst new file mode 100644 index 000000000..f92a732e3 --- /dev/null +++ b/docs/source/developers/guides/code/tips.rst @@ -0,0 +1,2 @@ +Tips +==== diff --git a/docs/source/developers/guides/docs/doc_guidelines.rst b/docs/source/developers/guides/docs/doc_guidelines.rst new file mode 100644 index 000000000..a91d0f23e --- /dev/null +++ b/docs/source/developers/guides/docs/doc_guidelines.rst @@ -0,0 +1,255 @@ +Guidelines for xCAT Documentation +================================= +The following guidelines should be followed when making changes to the xCAT documentation to help create consistency in the documentation. + +Document Structure +------------------ + +Section Structure +````````````````` + +xCAT doc page may have 4 levels of title at most: :: + + The First Title + =============== + + The Second Title + ---------------- + + The Third Title + ``````````````` + + The Forth Title + ''''''''''''''' + +List Structure +`````````````` + +Bullet Lists +'''''''''''' + +* Bullet one + + The Content. +* Bullet Two + + The Content. + +:: + + * Bullet one + The Content. + * Bullet Two + The Content. + +Enumerated List +''''''''''''''' + +1. Item 1 + + a) item a + b) item b + +2. Item 2 + + a) item a + +:: + + 1. Item 1 + a) item a + b) item b + 2. Item 2 + a) item a + +Hyperlinks -> Internal Links -> External Links +---------------------------------------------- + +Add links to refer other web page is a very common way in writting document, it's very helpful to reduce the doc duplication and make doc to be easy to understand. Following are several ways to add a link in the xCAT documentation. + +* **Add an Internal Link to ``Customized Link Target``** + + ``Customized Link Target`` means a user defined **Link Target**. + +.. _my_link_target: + + Define a **Link Target** named ``my_link_target``: :: + + .. _my_link_target: + + **Customized Link Target** + + This part of content is a link target which can be linked by other content. + +.. + + Link to the customized link target ``my_link_target`` :ref:`my link `: :: + + Link to the customized link target ``my_link_target`` :ref:`my link ` + +.. + + ``Usage:`` This method is used to add a **Link Target** in any page that can be referred by any other pages. + +* **Add an Internal Link to Current Page** + + Link to an internal section in current page: `Guidelines for xCAT Documentation`_: :: + + Link to an internal section in current page: `Guidelines for xCAT Documentation`_ + +.. + + ``Usage:`` Every title of a section is an auto-generated 'link target', so you can use it directly. But it's only available inside the current page. + +* **Add an Internal Link to Other Page via File Path** + + Link to page ``http://server/overview/suport_list.html`` with **absolute file path** :doc:`support list `: :: + + Link to page ``http://server/overview/suport_list.html`` with **absolute file path** :doc:`support list ` + +.. + + Link to page ``http://server/overview/suport_list.html`` with **relative file path** :doc:`support list <../overview/support_list>`: :: + + Link to page ``http://server/overview/suport_list.html`` with **relative file path** :doc:`support list <../overview/support_list>` + +.. + + ``Usage:`` When you want to link to another whole page but don't want to make a ``Customized Link Target`` in that source page, you can use the file path to link it directly. + +* **Add an External Link** + + Link to an external web page: `google `_: :: + + Link to an external web page: `google `_ + +.. + + ``Usage:`` When you want to link to a page which does not belong to xCAT documentation. + + ``Note:`` The ``https://`` keyword must be added before the web page URL. + +* **Add a Link with Explicit URL Displayed** + + Link to http://www.google.com: :: + + Link to http://www.google.com + +.. + + ``Usage:`` Make a link and display the URL. + + +Add OS or ARCH Specific Contents +-------------------------------- + +When writing a common xCAT doc, we always encounter the case that certain small part of content needs to be OS or ARCH specific. In this case, please use the following format to add specific branches. + +The keyword in the **[]** can be an OS name or ARCH name, or any name which can distinguish the content from other part. + +The valid keyword includes: **RHEL**, **SLES**, **UBUNTU**, **CENTOS**, **X86_64**, **PPC64**, **PPC64LE**. If the keyword is an OS, it can be postfixed with an OS version e.g. RHEL7. + +* **[RHEL7]** + + This part of description is for [rh7] specific. + +* **[SLES]** + + This part of description is for [sles] specific. + +* **[PPC64LE]** + + This part of description is for [ppc64le] specific. + +:: + + * **[RHEL7]** + + This part of description is for [rh7] specific. + + +Miscellaneous +------------- + +Add a Comment +````````````` + +.. Try the comment + +The sentence started with ``..`` will be a comment that won't be displayed in the doc. :: + + .. This is a comment + +Add Literal Block +````````````````` + +If you want to add a paragraph of code or something that don't want to be interpreted by browser: :: + + If you want to add a paragraph of code or something that don't want to be interpreted by browser: :: + #lsdef node1 + #tabdump + +Decorate Word +````````````` + +If you want to display one or several words to be ``Literal Word``: :: + + If you want to display one or several words to be ``Literal Word`` + +If you want to make a **strong emphasis** of the word: :: + + If you want to make a **strong emphasis** of the word: + +Add a Table +``````````` + +Add a table in the doc: + ++------------+------------+-----------+ +| Header 1 | Header 2 | Header 3 | ++============+============+===========+ +| body row 1 | column 2 | column 3 | ++------------+------------+-----------+ +| body row 2 | Cells may span columns.| ++------------+------------+-----------+ +| body row 3 | Cells may | - Cells | ++------------+ span rows. | - contain | +| body row 4 | | - blocks. | ++------------+------------+-----------+ + +:: + + +------------+------------+-----------+ + | Header 1 | Header 2 | Header 3 | + +============+============+===========+ + | body row 1 | column 2 | column 3 | + +------------+------------+-----------+ + | body row 2 | Cells may span columns.| + +------------+------------+-----------+ + | body row 3 | Cells may | - Cells | + +------------+ span rows. | - contain | + | body row 4 | | - blocks. | + +------------+------------+-----------+ + +Add Footnotes +````````````` + +This is the first example of footnotes [1]_. + +This is the second example of footnotes [2]_. + +:: + + This is the first example of footnotes [1]_. + This is the second example of footnotes [2]_. + + .. [1] First footnote + .. [2] Second footnote + +------------------------ + +.. [1] First footnote +.. [2] Second footnote + + + diff --git a/docs/source/developers/guides/docs/index.rst b/docs/source/developers/guides/docs/index.rst new file mode 100644 index 000000000..ef0c70251 --- /dev/null +++ b/docs/source/developers/guides/docs/index.rst @@ -0,0 +1,7 @@ +Documentation +============= + +.. toctree:: + :maxdepth: 2 + + doc_guidelines.rst diff --git a/docs/source/developers/guides/index.rst b/docs/source/developers/guides/index.rst new file mode 100644 index 000000000..a30897263 --- /dev/null +++ b/docs/source/developers/guides/index.rst @@ -0,0 +1,8 @@ +Guides +====== + +.. toctree:: + :maxdepth: 2 + + docs/index.rst + code/index.rst diff --git a/docs/source/developers/index.rst b/docs/source/developers/index.rst index df2ce9334..a56f0e63a 100644 --- a/docs/source/developers/index.rst +++ b/docs/source/developers/index.rst @@ -9,7 +9,4 @@ This page is for developers interested in working with xCAT. license/index.rst github/index.rst - doc_guidelines.rst - developer_guide.rst - programming_tips.rst - debug_xcat.rst + guides/index.rst diff --git a/docs/source/developers/programming_tips.rst b/docs/source/developers/programming_tips.rst deleted file mode 100644 index 529c10e42..000000000 --- a/docs/source/developers/programming_tips.rst +++ /dev/null @@ -1,2 +0,0 @@ -Programming Tips -================