Fix a manpage for EasyBuild #271

fgeorgatos · 2012-10-11T23:59:49Z

Hi,

I made an example draft in ReST (rst2man parses it nicely); feel free to hack it around as you fancy.

[root@ui10 rst2man]# cat eb.txt 
=========
EasyBuild
=========

----------------------------------------------------------------------------------------------------------------------------------------------------------
EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.
----------------------------------------------------------------------------------------------------------------------------------------------------------

:Author: fotis@cern.ch
:Date:   2012-10-12
:Copyright: CC-BY-SA
:Version: 0.1
:Manual section: 8
:Manual group: administrator commands

.. TODO: Fotis Georgatos <Fotis.Georgatos@uni.lu> # Add other manpage authors as needed

SYNOPSIS
========

  eb.py [options] easyconfig [..]

DESCRIPTION
===========

Build a software package based on easyconfig (or parse a directory). 
Provide one or more easyconfigs or directories, use -h or --help more information.

OPTIONS
=======

  -h, --help            show the help message and exit

  Basic options:
    Basic runtime options for EasyBuild.

    -b BLOCKS, --only-blocks=BLOCKS
                        Only build blocks blk[,blk2]
    -d, --debug         log debug messages
    -f, --force         force to rebuild software even if it's already
                        installed (i.e. can be found as module)
    --job               will submit the build as a job
    -k, --skip          skip existing software (useful for installing
                        additional packages)
    -l                  log to stdout
    -r PATH, --robot=PATH
                        path to search for easyconfigs for missing
                        dependencies
    -s STOP, --stop=STOP
                        stop the installation after certain step (valid: cfg,
                        source, patch, prepare, configure, make, install,
                        test, postproc, cleanup, packages)
    --strict=STRICT     set strictness level (possible levels: ignore, warn,
                        error)

  Software build options:
    Specify software build options; the regular versions of these options
    will only search for matching easyconfigs, while the --try-X versions
    will cause EasyBuild to try and generate a matching easyconfig based
    on available ones if no matching easyconfig is found (NOTE: best
    effort, might produce wrong builds!)

    --software-name=NAME
                        build software with name

    --software-version=VERSION
                        build software with version

    --toolkit=NAME,VERSION
                        build with toolkit (name and version)

    --toolkit-name=NAME
                        build with toolkit name

    --toolkit-version=VERSION
                        build with toolkit version

    --amend=VAR=VALUE[,VALUE]
                        specify additional build parameters (can be used
                        multiple times); for example: versionprefix=foo or
                        patches=one.patch,two.patch)

    --try-software-name=NAME
                        try to build software with name (USE WITH CARE!)

    --try-software-version=VERSION
                        try to build software with version (USE WITH CARE!)

    --try-toolkit=NAME,VERSION
                        try to build with toolkit (name and version) (USE WITH CARE!)

    --try-toolkit-name=NAME
                        try to build with toolkit name (USE WITH CARE!)

    --try-toolkit-version=VERSION
                        try to build with toolkit version (USE WITH CARE!)

    --try-amend=VAR=VALUE[,VALUE]
                        try to specify additional build parameters (can be
                        used multiple times); for example: versionprefix=foo
                        or patches=one.patch,two.patch) (USE WITH CARE!)

  Override options:
    Override default EasyBuild behavior.

    -C CONFIG, --config=CONFIG
                        path to EasyBuild config file
                        [default: $EASYBUILDCONFIG or easybuild/easybuild_config.py]
    -e CLASS, --easyblock=CLASS
                        loads the class from module to process the spec file
                        or dump the options for [default: Application class]
    -p, --pretend       does the build/installation in a test directory
                        located in $HOME/easybuildinstall [default:
                        $EASYBUILDINSTALLDIR or installPath in EasyBuild
                        config file]
    -t, --skip-tests    skip testing

  Informative options:
    Obtain information about EasyBuild.

    -a, --avail-easyconfig-params
                        show available easyconfig parameters
    --dump-classes      show list of available classes
    --search=SEARCH     search for module-files in the robot-directory
    -v, --version       show version

    --dep-graph=depgraph.<ext>
                        create dependency graph

  Regression test options:
    Run and control an EasyBuild regression test.

    --regtest           enable regression test mode
    --regtest-online    enable online regression test mode
    --sequential        specify this option if you want to prevent parallel
                        build
    --regtest-output-dir=REGTEST_OUTPUT_DIR
                        set output directory for test-run
    --aggregate-regtest=AGGREGATE_REGTEST
                        collect all the xmls inside the given directory and
                        generate a single file


PROBLEMS
========

1. EasyBuild does not make coffee ; read Linux Coffee-HOWTO

SEE ALSO
========

 * `EasyBuild homepage <http://hpcugent.github.com/easybuild/>`__
 * `EasyBuild framework repository <https://github.com/hpcugent/easybuild>`__
 * `EasyBuild experimental repository <https://github.com/fgeorgatos/easybuild.experimental>`__
 * ``man 8 eb``

BUGS
====

 * "this software has no bugs - only features" (TM)

 * --try-X versions
    will cause EasyBuild to try and generate a matching easyconfig based
    on available ones if no matching easyconfig is found.
    NOTE: this is best effort and might produce wrong builds!

 * Discussion about the tool's specification is still open.

 * `Report any unknown issue at the github tracker <https://github.com/hpcugent/easybuild/issues>`__

The text was updated successfully, but these errors were encountered:

fgeorgatos · 2012-10-12T00:01:35Z

hm... I come to realize that CC-BY-SA may not be proper since this is derivative work. Modify it as you see fit.

boegel · 2012-10-22T09:13:07Z

We should have a script that generates this, so e.g. the list of options remains up-to-date.

Would you be willing to look into that? The script should go into easybuild/scripts.

fgeorgatos · 2012-10-22T14:37:54Z

On Mon, Oct 22, 2012 at 11:13 AM, Kenneth Hoste notifications@git.luolix.topwrote:

We should have a script that generates this, so e.g. the list of options
remains up-to-date.

Would you be willing to look into that? The script should go into
easybuild/scripts.

If I am to do that, I might as well recycle the output of eb -h AS-IS via a
shell script;
and automagically produce the .rst; but, is that going to be good enough?
(I doubt).

Fotis

JensTimmerman · 2012-10-22T15:10:07Z

I would prefer you wrote it in python, not shell

you could use this

>>> from optparse import OptionParser
>>> from easybuild.main import add_cmdline_options
>>> parser = OptionParser()
>>> add_cmdline_options(parser)
>>> helpmessage = parser.format_help()

But shell would be acceptable...

JensTimmerman · 2012-11-07T14:29:49Z

extending the parser's formatter to directly generate a man page would even be better! (We could look into that in generaloption.py from VSC-tools ;-))

fgeorgatos · 2012-11-15T17:30:59Z

Hi there,

Two things, the first one is a bit high priority:

There's a typo in the output of eb -h which would confuse newcomers:
EASYBUILDINSTALLDIR vs EASYBUILDINSTALLPATH # please fix!
I have produced another manpage in rst format, based on v1.0's output;
alas, it was not possible to automate the procedure, see at the end why

=========
EasyBuild
=========

----------------------------------------------------------------------------------------------------------------------------------------------------------
EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.
----------------------------------------------------------------------------------------------------------------------------------------------------------

:Author: Fotis Georgatos <Fotis.Georgatos@cern.ch> # for the manpage
:Date:   2012-11-15
:Copyright: CC-BY-SA
:Version: 1.0
:Manual section: 1
:Manual group: General commands

.. TODO: Fotis Georgatos <Fotis.Georgatos@uni.lu> # Add other manpage authors as needed

SYNOPSIS
========

  ``eb`` [options] easyconfig [..]

DESCRIPTION
===========

Build a software package based on easyconfig (or parse a directory). 
Provide one or more easyconfigs or directories, use -h or --help more information.

OPTIONS
=======

Usage: eb [options] easyconfig [..]

Builds software based on easyconfig (or parse a directory) Provide one or more
easyconfigs or directories, use -h or --help more information.

Options:
  -h, --help            show this help message and exit

  Basic options:
    Basic runtime options for EasyBuild.

    -b BLOCKS, --only-blocks=BLOCKS
                        Only build blocks blk[,blk2]
    -d, --debug         log debug messages
    -f, --force         force to rebuild software even if it's already
                        installed (i.e. can be found as module)
    --job               will submit the build as a job
    -k, --skip          skip existing software (useful for installing
                        additional packages)
    -l                  log to stdout
    -r, --robot         path to search for easyconfigs for missing
                        dependencies (default: easybuild-easyconfigs install
                        path)
    -s STOP, --stop=STOP
                        stop the installation after certain step (valid: cfg,
                        source, patch, prepare, configure, make, install,
                        test, postproc, cleanup, extensions)
    --strict=STRICT     set strictness level (possible levels: ignore, warn,
                        error)

  Software build options:
    Specify software build options; the regular versions of these options
    will only search for matching easyconfigs, while the --try-X versions
    will cause EasyBuild to try and generate a matching easyconfig based
    on available ones if no matching easyconfig is found (NOTE: best
    effort, might produce wrong builds!)

    --software-name=NAME
                        build software with name

    --software-version=VERSION
                        build software with version

    --toolchain=NAME,VERSION
                        build with toolchain (name and version)

    --toolchain-name=NAME
                        build with toolchain name

    --toolchain-version=VERSION
                        build with toolchain version

    --amend=VAR=VALUE[,VALUE]
                        specify additional build parameters (can be used
                        multiple times); for example: versionprefix=foo or
                        patches=one.patch,two.patch)

    --try-software-name=NAME
                        try to build software with name (USE WITH CARE!)

    --try-software-version=VERSION
                        try to build software with version (USE WITH CARE!)

    --try-toolchain=NAME,VERSION
                        try to build with toolchain (name and version) (USE
                        WITH CARE!)

    --try-toolchain-name=NAME
                        try to build with toolchain name (USE WITH CARE!)

    --try-toolchain-version=VERSION
                        try to build with toolchain version (USE WITH CARE!)

    --try-amend=VAR=VALUE[,VALUE]
                        try to specify additional build parameters (can be
                        used multiple times); for example: versionprefix=foo
                        or patches=one.patch,two.patch) (USE WITH CARE!)

  Override options:
    Override default EasyBuild behavior.

    -C CONFIG, --config=CONFIG
                        path to EasyBuild config file [default:
                        $EASYBUILDCONFIG or easybuild/easybuild_config.py]

    -e CLASS, --easyblock=CLASS
                        loads the class from module to process the spec file
                        or dump the options for [default: Application class]

    -p, --pretend       does the build/installation in a test directory
                        located in $HOME/easybuildinstall [default:
                        $EASYBUILDINSTALLPATH or install_path in EasyBuild
                        config file]

    -t, --skip-test-cases
                        skip running test cases

  Informative options:
    Obtain information about EasyBuild.

    -a, --avail-easyconfig-params
                        show available easyconfig parameters

    --list-easyblocks=LIST_EASYBLOCKS
                        show list of available easyblocks

    --search=STR        search for module-files in the robot-directory

    -v, --version       show version

    --dep-graph=depgraph.<ext>
                        create dependency graph

  Regression test options:
    Run and control an EasyBuild regression test.

    --regtest           enable regression test mode
    --regtest-online    enable online regression test mode
    --sequential        specify this option if you want to prevent parallel build

    --regtest-output-dir=DIR
                        set output directory for test-run

    --aggregate-regtest=DIR
                        collect all the xmls inside the given directory and generate a single file

PROBLEMS
========

#1. EasyBuild does not make coffee yet ; read Linux Coffee-HOWTO instead

SEE ALSO
========

 * man eb # <-- YOU ARE HERE
 * EasyBuild homepage: http://hpcugent.github.com/easybuild/ # general information
 * EasyBuild framework repository: https://github.com/hpcugent/easybuild-framework # source
 * EasyBuild experimental repository: https://github.com/fgeorgatos/easybuild.experimental # area51

BUGS
====

 * "this software has no bugs - only features" (TM) ; read below about how to find them

 * Report any unknown issue at the github tracker: https://github.com/hpcugent/easybuild/issues

OK, in order to automatically produce the manpage, we need to fix:

the way the output is produced had to be tuned a bit for rst compliance: try a diff
(being specific: more spaces should separate options, otherwise rst2man complains)
add the list of names of software developers and/or preferred mailing list to contact at
follow Jens's advice overall ;-)

I had to do this in the quick'n'dirty manner since I have the uni.lu folks now using the tool!

If you need to, I can submit to you the produced file, mine is at a destination like:
/opt/apps/default/software/easybuild/1.0/share/man/man1/eb.1
but I think you're big boys and can make it with rst2man just fine :-)

hey, a big applause from this end for the SC12 rollout!

Fotis

boegel · 2012-11-15T19:25:19Z

Hi Fotis,

Can you open an issue for 1), with a critical label in the easybuild-framework repo?
I know it's an easy fix, and we should fix it ASAP, but we're not going to ship a new release just because of this.

It's important to have a track record on issues, even the smallest ones.

Man page looks good, we can clean up the help output as a part of the issue for 1) to automate the procedure.

K.

Op 15 Nov 2012 om 10:31 heeft Fotis Georgatos notifications@github.com het volgende geschreven:

Hi there,

Two things, the first one is a bit high priority:

There's a typo in the output of eb -h which would confuse newcomers:
EASYBUILDINSTALLDIR vs EASYBUILDINSTALLPATH # please fix!

I have produced another manpage in rst format, based on v1.0's output;
alas, it was not possible to automate the procedure, see at the end why

EasyBuild

EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.

:Author: Fotis Georgatos Fotis.Georgatos@cern.ch # for the manpage
:Date: 2012-11-15
:Copyright: CC-BY-SA
:Version: 1.0
:Manual section: 1
:Manual group: General commands

.. TODO: Fotis Georgatos Fotis.Georgatos@uni.lu # Add other manpage authors as needed

SYNOPSIS

eb [options] easyconfig [..]

DESCRIPTION

Build a software package based on easyconfig (or parse a directory).
Provide one or more easyconfigs or directories, use -h or --help more information.

OPTIONS

Usage: eb [options] easyconfig [..]

Builds software based on easyconfig (or parse a directory) Provide one or more
easyconfigs or directories, use -h or --help more information.

Options:
-h, --help show this help message and exit

Basic options:
Basic runtime options for EasyBuild.
-b BLOCKS, --only-blocks=BLOCKS
                    Only build blocks blk[,blk2]
-d, --debug         log debug messages
-f, --force         force to rebuild software even if it's already
                    installed (i.e. can be found as module)
--job               will submit the build as a job
-k, --skip          skip existing software (useful for installing
                    additional packages)
-l                  log to stdout
-r, --robot         path to search for easyconfigs for missing
                    dependencies (default: easybuild-easyconfigs install
                    path)
-s STOP, --stop=STOP
                    stop the installation after certain step (valid: cfg,
                    source, patch, prepare, configure, make, install,
                    test, postproc, cleanup, extensions)
--strict=STRICT     set strictness level (possible levels: ignore, warn,
                    error)
Software build options:
Specify software build options; the regular versions of these options
will only search for matching easyconfigs, while the --try-X versions
will cause EasyBuild to try and generate a matching easyconfig based
on available ones if no matching easyconfig is found (NOTE: best
effort, might produce wrong builds!)
--software-name=NAME
                    build software with name

--software-version=VERSION
                    build software with version

--toolchain=NAME,VERSION
                    build with toolchain (name and version)

--toolchain-name=NAME
                    build with toolchain name

--toolchain-version=VERSION
                    build with toolchain version

--amend=VAR=VALUE[,VALUE]
                    specify additional build parameters (can be used
                    multiple times); for example: versionprefix=foo or
                    patches=one.patch,two.patch)

--try-software-name=NAME
                    try to build software with name (USE WITH CARE!)

--try-software-version=VERSION
                    try to build software with version (USE WITH CARE!)

--try-toolchain=NAME,VERSION
                    try to build with toolchain (name and version) (USE
                    WITH CARE!)

--try-toolchain-name=NAME
                    try to build with toolchain name (USE WITH CARE!)

--try-toolchain-version=VERSION
                    try to build with toolchain version (USE WITH CARE!)

--try-amend=VAR=VALUE[,VALUE]
                    try to specify additional build parameters (can be
                    used multiple times); for example: versionprefix=foo
                    or patches=one.patch,two.patch) (USE WITH CARE!)
Override options:
Override default EasyBuild behavior.
-C CONFIG, --config=CONFIG
                    path to EasyBuild config file [default:
                    $EASYBUILDCONFIG or easybuild/easybuild_config.py]

-e CLASS, --easyblock=CLASS
                    loads the class from module to process the spec file
                    or dump the options for [default: Application class]

-p, --pretend       does the build/installation in a test directory
                    located in $HOME/easybuildinstall [default:
                    $EASYBUILDINSTALLPATH or install_path in EasyBuild
                    config file]

-t, --skip-test-cases
                    skip running test cases
Informative options:
Obtain information about EasyBuild.
-a, --avail-easyconfig-params
                    show available easyconfig parameters

--list-easyblocks=LIST_EASYBLOCKS
                    show list of available easyblocks

--search=STR        search for module-files in the robot-directory

-v, --version       show version

--dep-graph=depgraph.<ext>
                    create dependency graph
Regression test options:
Run and control an EasyBuild regression test.
--regtest           enable regression test mode
--regtest-online    enable online regression test mode
--sequential        specify this option if you want to prevent parallel build

--regtest-output-dir=DIR
                    set output directory for test-run

--aggregate-regtest=DIR
                    collect all the xmls inside the given directory and generate a single file
PROBLEMS

#1. EasyBuild does not make coffee yet ; read Linux Coffee-HOWTO instead

SEE ALSO

man eb # <-- YOU ARE HERE

EasyBuild homepage: http://hpcugent.github.com/easybuild/ # general information

EasyBuild framework repository: https://github.com/hpcugent/easybuild-framework # source

EasyBuild experimental repository: https://github.com/fgeorgatos/easybuild.experimental # area51

BUGS

"this software has no bugs - only features" (TM) ; read below about how to find them

Report any unknown issue at the github tracker: https://github.com/hpcugent/easybuild/issues

OK, in order to automatically produce the manpage, we need to fix:

the way the output is produced had to be tuned a bit for rst compliance: try a diff (being specific: more spaces should separate options, otherwise rst2man complains)
add the list of names of software developers and/or preferred mailing list to contact at
follow Jens's advice overall ;-)
I had to do this in the quick'n'dirty manner since I have the uni.lu folks now using the tool!

If you need to, I can submit to you the produced file, mine is at a destination like:
/opt/apps/default/software/easybuild/1.0/share/man/man1/eb.1
but I think you're big boys and can make it with rst2man just fine :-)

hey, a big applause from this end for the SC12 rollout!

Fotis

—
Reply to this email directly or view it on GitHub.

boegel modified the milestone: v1.X Jun 24, 2015

fgeorgatos mentioned this issue Jul 8, 2016

bump version to 2.8.2 & update release notes #1836

Merged

boegel modified the milestone: 3.x May 2, 2017

boegel removed the documentation label Oct 30, 2017

boegel modified the milestones: 3.x, 4.x Feb 20, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix a manpage for EasyBuild #271

Fix a manpage for EasyBuild #271

fgeorgatos commented Oct 11, 2012

fgeorgatos commented Oct 12, 2012

boegel commented Oct 22, 2012

fgeorgatos commented Oct 22, 2012

JensTimmerman commented Oct 22, 2012

JensTimmerman commented Nov 7, 2012

fgeorgatos commented Nov 15, 2012

boegel commented Nov 15, 2012

EasyBuild

EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.

SYNOPSIS

DESCRIPTION

OPTIONS

PROBLEMS

SEE ALSO

BUGS

Fix a manpage for EasyBuild #271

Fix a manpage for EasyBuild #271

Comments

fgeorgatos commented Oct 11, 2012

fgeorgatos commented Oct 12, 2012

boegel commented Oct 22, 2012

fgeorgatos commented Oct 22, 2012

JensTimmerman commented Oct 22, 2012

JensTimmerman commented Nov 7, 2012

fgeorgatos commented Nov 15, 2012

boegel commented Nov 15, 2012

EasyBuild

EasyBuild is a software build and installation framework written in Python that allows you to install software in a structured, repeatable and robust way.

SYNOPSIS

DESCRIPTION

OPTIONS

PROBLEMS

SEE ALSO

BUGS