Additional easyconfig parameters for documentation (REVIEW) #2113
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -36,13 +36,14 @@ | |
| import re | ||
| import sys | ||
| import tempfile | ||
| from textwrap import wrap | ||
| from vsc.utils import fancylogger | ||
| from vsc.utils.missing import get_subclasses | ||
|
|
||
| from easybuild.tools.build_log import EasyBuildError | ||
| from easybuild.tools.config import build_option, get_module_syntax, install_path | ||
| from easybuild.tools.filetools import convert_name, mkdir, read_file, remove_file, resolve_path, symlink, write_file | ||
| from easybuild.tools.modules import ROOT_ENV_VAR_NAME_PREFIX, modules_tool | ||
| from easybuild.tools.utilities import quote_str | ||
|
|
||
|
|
||
|
|
@@ -298,6 +299,100 @@ def use(self, paths, prefix=None, guarded=False): | |
| """ | ||
| raise NotImplementedError | ||
|
|
||
| def _generate_help_text(self): | ||
| """ | ||
| Generate syntax-independent help text used for `module help`. | ||
| """ | ||
|
|
||
| def generate_section(sec_name, sec_txt, strip=False): | ||
| """ | ||
| Generate section with given name and contents. | ||
| """ | ||
| if sec_txt: | ||
| if strip: | ||
| text = sec_txt.strip() | ||
| else: | ||
| text = sec_txt | ||
|
|
||
| return [ | ||
| '', | ||
| '', | ||
| sec_name, | ||
| '=' * len(sec_name), | ||
| text, | ||
| ] | ||
| else: | ||
| return [] | ||
|
||
|
|
||
| # General package description (mandatory) | ||
| lines = generate_section('Description', self.app.cfg['description'], strip=True) | ||
|
|
||
| # Package usage instructions (optional) | ||
| lines.extend(generate_section('Usage', self.app.cfg['usage'], strip=True)) | ||
|
|
||
| # Examples (optional) | ||
| lines.extend(generate_section('Examples', self.app.cfg['examples'], strip=True)) | ||
|
|
||
| # Additional information: homepage + (if available) doc paths/urls, upstream/site contact | ||
| lines.extend(generate_section("More information", " - Homepage: %s" % self.app.cfg['homepage'])) | ||
|
|
||
| docpaths = self.app.cfg['docpaths'] or [] | ||
| docurls = self.app.cfg['docurls'] or [] | ||
| if docpaths or docurls: | ||
| env_name = convert_name(self.app.name, upper=True) | ||
| root_envvar = ROOT_ENV_VAR_NAME_PREFIX + env_name | ||
|
||
| lines.extend([" - Documentation:"]) | ||
| lines.extend([" - $%s/%s" % (root_envvar,path) for path in docpaths]) | ||
|
||
| lines.extend([" - %s" % url for url in docurls]) | ||
|
|
||
| upstream = self.app.cfg['upstream_contact'] | ||
| if upstream: | ||
|
||
| if isinstance(upstream, list): | ||
| lines.extend([" - Upstream contacts:"]) | ||
| lines.extend([" - %s" % address for address in upstream]) | ||
|
||
| else: | ||
| lines.extend([" - Upstream contact: %s" % upstream]) | ||
|
|
||
| site_contact = self.app.cfg['site_contact'] | ||
| if site_contact: | ||
| if isinstance(site_contact, list): | ||
| lines.extend([" - Site contacts:"]) | ||
|
||
| lines.extend([" - %s" % address for address in site_contact]) | ||
|
||
| else: | ||
| lines.extend([" - Site contact: %s" % site_contact]) | ||
|
||
|
|
||
| # Extensions (if any) | ||
| extensions = self._generate_extension_list() | ||
| lines.extend(generate_section("Included extensions", '\n'.join(wrap(extensions, 78)))) | ||
|
|
||
| return '\n'.join(lines) | ||
|
|
||
| def _generate_whatis_lines(self): | ||
| """ | ||
| Generate a list of entries used for `module whatis`. | ||
| """ | ||
| whatis = self.app.cfg['whatis'] | ||
| if whatis is None: | ||
| # default: include 'whatis' statements with description, homepage, and extensions (if any) | ||
| whatis = [ | ||
| "Description: %s" % self.app.cfg['description'], | ||
| "Homepage: %s" % self.app.cfg['homepage'] | ||
| ] | ||
| extensions = self._generate_extension_list() | ||
| if extensions: | ||
| whatis.append("Extensions: %s" % extensions) | ||
|
|
||
| return whatis | ||
|
|
||
| def _generate_extension_list(self): | ||
|
||
| """ | ||
| Generate a string with a comma-separated list of extensions. | ||
| """ | ||
| exts_list = self.app.cfg['exts_list'] | ||
| extensions = ', '.join(sorted(['%s-%s' % (ext[0], ext[1]) for ext in exts_list], key=str.lower)) | ||
|
||
|
|
||
| return extensions | ||
|
|
||
|
|
||
| class ModuleGeneratorTcl(ModuleGenerator): | ||
| """ | ||
|
|
@@ -346,16 +441,9 @@ def get_description(self, conflict=True): | |
| """ | ||
| Generate a description. | ||
| """ | ||
| lines = [ | ||
| "proc ModulesHelp { } {", | ||
| " puts stderr {%s" % self._generate_help_text(), | ||
| " }", | ||
| '}', | ||
| '', | ||
|
|
@@ -376,10 +464,11 @@ def get_description(self, conflict=True): | |
| # - 'conflict Compiler/GCC/4.8.2/OpenMPI' for 'Compiler/GCC/4.8.2/OpenMPI/1.6.4' | ||
| lines.extend(['', "conflict %s" % os.path.dirname(self.app.short_mod_name)]) | ||
|
|
||
| whatis = self._generate_whatis_lines() | ||
|
||
| txt = '\n'.join(lines + ['']) % { | ||
| 'name': self.app.name, | ||
| 'version': self.app.version, | ||
| 'description': self.app.cfg['description'], | ||
| 'whatis_lines': '\n'.join(["module-whatis {%s}" % line for line in whatis]), | ||
| 'installdir': self.app.installdir, | ||
| } | ||
|
|
@@ -601,16 +690,9 @@ def get_description(self, conflict=True): | |
| """ | ||
| Generate a description. | ||
| """ | ||
| lines = [ | ||
| 'help([[%s' % self._generate_help_text(), | ||
| ']])', | ||
| '', | ||
| "%(whatis_lines)s", | ||
| '', | ||
|
|
@@ -624,10 +706,11 @@ def get_description(self, conflict=True): | |
| # conflict on 'name' part of module name (excluding version part at the end) | ||
| lines.extend(['', 'conflict("%s")' % os.path.dirname(self.app.short_mod_name)]) | ||
|
|
||
| whatis = self._generate_whatis_lines() | ||
|
||
| txt = '\n'.join(lines + ['']) % { | ||
| 'name': self.app.name, | ||
| 'version': self.app.version, | ||
| 'description': self.app.cfg['description'], | ||
| 'whatis_lines': '\n'.join(["whatis([[%s]])" % line for line in whatis]), | ||
| 'installdir': self.app.installdir, | ||
| 'homepage': self.app.cfg['homepage'], | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
List of paths for documentation relative to installation directory