gen_easyblocks_docs.py

# #
# Copyright 2015-2023 Ghent University
#
# This file is part of EasyBuild,
# originally created by the HPC team of Ghent University (http://ugent.be/hpc/en),
# with support of Ghent University (http://ugent.be/hpc),
# the Flemish Supercomputer Centre (VSC) (https://vscentrum.be/nl/en),
# the Hercules foundation (http://www.herculesstichting.be/in_English)
# and the Department of Economy, Science and Innovation (EWI) (http://www.ewi-vlaanderen.be/en).
#
# https://github.com/easybuilders/easybuild
#
# EasyBuild is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation v2.
#
# EasyBuild is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with EasyBuild.  If not, see <http://www.gnu.org/licenses/>.
# #
"""
Generates documentation for (generic) easyblocks in MarkDown format

@author Caroline De Brouwer (Ghent University)
@author Kenneth Hoste (Ghent University)
"""

import os
import easybuild.tools.config as config

from easybuild.base.generaloption import simple_option
from easybuild.tools.docs import gen_easyblocks_overview_md
from easybuild.tools.filetools import write_file

COMMON_PARAMS = {
    'ConfigureMake': ['configopts', 'buildopts', 'installopts'],
    # needs to be extended
}
DOC_FUNCTIONS = ['build_step', 'configure_step', 'install_step']

DEFAULT_EXAMPLE_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'example_easyconfigs')
DEFAULT_MODULE = 'easybuild.easyblocks.generic'


options = {
    'out-file': ('Path to output file', 'string', 'store', None, 'o'),
    'examples': ('Path to dir that contains example files', 'string', 'store', DEFAULT_EXAMPLE_PATH, 'e'),
    'module': ('Name of module to load the easyblocks from', 'string', 'store', DEFAULT_MODULE, 'm')
}
so = simple_option(options)

config.init_build_options({'validate': False, 'external_modules_metadata': {}})

autogen_comment = [
    "<!---",
    "    This file is automatically generated using the %s script, " % os.path.basename(__file__),
    "    and information and docstrings from easyblocks and the EasyBuild framework.",
    "    Do not edit this file manually, but update the docstrings and regenerate it!",
    "-->",
    '',
]

easyblocks_overview = gen_easyblocks_overview_md(so.options.module, so.options.examples, COMMON_PARAMS, DOC_FUNCTIONS)

txt = '\n'.join(autogen_comment + easyblocks_overview)
if so.options.out_file:
    write_file(so.options.out_file, txt)
    print('%s updated' % so.options.out_file)
else:
    print(txt)