xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-05-22 03:32:04 +00:00
Code Issues Releases Wiki Activity

Merge pull request #307 from whowutwut/developer_guide

Browse Source 
Added documentation for building rst man pages
This commit is contained in:
Victor Hu 2015-10-28 09:57:44 -04:00
commit d35dd67667
12 changed files with 385 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
create_man_pages.py
View File

@ -1,4 +1,5 @@
#!/usr/bin/env python
#TODO: Delete the old files to support removing a man page
import glob
import os
@ -7,15 +8,49 @@ import subprocess
from glob import glob
import shutil
#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"
@ -77,7 +112,11 @@ 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)

2
docs/source/developers/debug_xcat.rst
View File

@ -1,2 +0,0 @@
Debug xCAT Problems
===================

2
docs/source/developers/developer_guide.rst
View File

@ -1,2 +0,0 @@
Developer Guide
===============

57
docs/source/developers/guides/code/builds.rst Normal file
View File

@ -0,0 +1,57 @@
Building Source Code
====================
xcat-core
---------
Clone the xCAT project from `GitHub <https://github.com/xcat2/xcat-core>`_::
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 <http://xcat-docs.readthedocs.org>`_ 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 <http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/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 <http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/lib/Pod/POM/View/Restructured.pm>`_
- `Pod-POM-2.00 <http://search.cpan.org/~neilb/Pod-POM-2.00/lib/Pod/POM.pm>`_
#. 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

2
docs/source/developers/guides/code/debug.rst Normal file
View File

@ -0,0 +1,2 @@
Debug Problems
==============

9
docs/source/developers/guides/code/index.rst Normal file
View File

@ -0,0 +1,9 @@
Code Development
================
.. toctree::
:maxdepth: 2
builds.rst
debug.rst
tips.rst

2
docs/source/developers/guides/code/tips.rst Normal file
View File

@ -0,0 +1,2 @@
Tips
====

255
docs/source/developers/guides/docs/doc_guidelines.rst Normal file
View File

@ -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 <my_link_target>`: ::
Link to the customized link target ``my_link_target`` :ref:`my link <my_link_target>`
..
``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 </overview/support_list>`: ::
Link to page ``http://server/overview/suport_list.html`` with **absolute 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>`: ::
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 <http://www.goole.com>`_: ::
Link to an external web page: `google <http://www.goole.com>`_
..
``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

7
docs/source/developers/guides/docs/index.rst Normal file
View File

@ -0,0 +1,7 @@
Documentation
=============
.. toctree::
:maxdepth: 2
doc_guidelines.rst

8
docs/source/developers/guides/index.rst Normal file
View File

@ -0,0 +1,8 @@
Guides
======
.. toctree::
:maxdepth: 2
docs/index.rst
code/index.rst

5
docs/source/developers/index.rst
View File

@ -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

2
docs/source/developers/programming_tips.rst
View File

@ -1,2 +0,0 @@
Programming Tips
================