Contributing

Welcome!

Thanks for your interest in the technical side of our project. Contributions to wBuild are a great way to level up your skill, tackle the problem you are facing with the program faster and receive some nice and fun Open Source experience! Last but not least, contributions are very welcome from our side, and they are greatly appreciated! You’ll help anybody using wBuild, and we’ll surely give a credit for you in contributors.

There are several ways to contribute:

Ways of contributing to wBuild

Bug reports

Report bugs at https://github.com/gagneurlab/wBuild/issues.

If you are reporting a bug, please include:

#### Environment

    Your operating system, version of wBuild, version of Snakemake; any further details of your particular local setup
    that could be relevant

#### Issue description

    Generally describe the issue.

#### Steps to reproduce the issue

    Describe what did you do in the context of program before the bug came out.
    For example:
        1. Initiate wBuild in project
        2. Remove wBuild.depend
        3. Launch snakemake publish rule
        ....

#### What's the expected result?

    Describe the result of your actions that you have expected.


#### What's the actual result?

    Describe the result of your actions that you have faced.


#### Additional details / screenshot

    Include any additional details that you consider relevant.

- ![Screenshot]()
-

Bug fixes

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open for your work. Initiative bug fixes are also highly welcome!

Implement features

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write documentation

wBuild could always use more documentation, whether as part of the official wBuild docs, in docstrings, or even on the web in blog posts, articles, and such.

Request/propose a feature

The best way to send feedback is to file an issue at https://github.com/gagneurlab/wBuild/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Working with wBuild code

Prepare

Please make sure you’ve read the user overview to understand the basics of wBuild - wBuild position in the Snakemake workflow, demo project as well as features list could be especially interesting here.

Setting up the development environment

Ready to contribute? Here’s how to set up wbuild for local development.

  1. Fork the wbuild repo on GitHub.

  2. Clone your fork locally:

    $ git clone git@github.com:your_name_here/wbuild.git

  3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:

    $ mkvirtualenv wbuild
$ cd wbuild/
$ python setup.py develop

  4. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  5. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

    $ flake8 wbuild tests
$ python setup.py test or py.test
$ tox

    To get flake8 and tox, just pip install them into your virtualenv.

  6. Commit your changes and push your branch to GitHub:

    $ git add .
$ git commit -m "Your detailed description of your changes."
$ git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub website.

If the pull request adds functionality, we kindly ask you to also update the docs, telling about this new cool stuff! Put your new functionality into a function with a docstring, and add this feature to the list in README.rst.

Code documentation

The code of wBuild is well-documented, and it would be nice to keep it that way. Apart from looking in the code, here you find the documentation for the functions of wBuild:

CLI (wbuild.cli)

CLI interface to wbuild.

wbuild.cli.setup_paths()[source]

Setup the wbuild paths

Files scanning (wbuild.scanFiles)

wbuild.scanFiles.dumpSMRule(ruleInfos, outputFile, inputFile)[source]

Write the rule to the file.

Parameters:
  • ruleInfos – dictionary containing all the rule’s data
  • outputFile – file to print the rule to
  • inputFile – the object of the rule
wbuild.scanFiles.escapeSMString(item)[source]

Convert item to the appropriate string representation.

Parameters:item – string or dict
Returns:“key = ‘value’” (dict), “‘value’” (string) or ‘’ (other type)
wbuild.scanFiles.insertPlaceholders(dest, source)[source]

Infer placeholders’ substitutions.

Parameters:
  • dest – string to replace placeholders in
  • source – file; from its path we infer the placeholders values
Returns:

dest with replaced placeholders
wbuild.scanFiles.joinEmpty(string_list)[source]
Parameters:string_list –
Returns:sting representation of a list without the blank elements.
wbuild.scanFiles.writeDependencyFile()[source]

Entry point for writing .wBuild.depend.

wbuild.scanFiles.writeIndexRule(wbData, mdData, file, ignoreMD=False, dump=False)[source]

Write the rule of mapping the R and md wbData to the index.html.

Parameters:
  • wbRRows – info dict parsed from R wB files
  • wbMDrows – info dict parsed from MD wB files
  • file – file to print the index rule to
wbuild.scanFiles.writeMdRule(ruleInfos, file)[source]
Parameters:
  • ruleInfos –
  • file – file to write the rule to
wbuild.scanFiles.writeRule(r, file, dump=False)[source]

Write Snakemake rule from the parsed WB header informations.

Parameters:
  • r – parsed WB data dictionary entry
  • file – to write the rule to
wbuild.scanFiles.writeWBParseDependencyFile(filename)[source]

Entry point for writing .wBuild.depend. for the wbParseFunction in R

Service functions (wbuild.utils)

wbuild.utils.checkFilename(filename)[source]
Parameters:filename – to check
Returns:has appropriate name?
Raises:ValueError if the name is inappropriate
wbuild.utils.findFilesRecursive(startingPath, patterns)[source]
Parameters:
  • startingPath – root path of the search
  • patterns – patterns to search file names for
Returns:

paths to files matching the patterns
wbuild.utils.hasYAMLHeader(filepath)[source]
Parameters:filepath – path to the file
Returns:file contains YAML header?
wbuild.utils.linuxify(winSepStr, doubleBackslash=False)[source]

Convert windows (path) string to the linux format.

Parameters:
  • winSepStr – (path) string with windows-like “” separators
  • doubleBackslash – if the slashes in the winSepStr are double (happens when you read a macro string raw. Ex.: “C:Program Filesa.txt”
Returns:

str with substituted “” -> “/”
wbuild.utils.parseMDFiles(script_dir='Scripts', htmlPath='Output/html', readmePath=None)[source]
Parameters:
  • script_dir – Relative path to the Scripts directory
  • htmlPath – Relative path to the html output path
  • readmePath – Relative path to the readme
Returns:

a list of dictionaries with fields: - file - what is the input .md file - outputFile - there to put the output html file - param - parsed yaml header - always an empty list
wbuild.utils.parseWBInfosFromRFile(filename, htmlPath='Output/html')[source]
Parameters:
  • filename – Relative path to the Scripts directory
  • htmlPath – Relative path to the html output path
Returns:

a list of dictionaries with fields: - filen - what is the input R file - outputFile - there to put the output html file - param - parsed yaml params
wbuild.utils.parseWBInfosFromRFiles(script_dir='Scripts', htmlPath='Output/html')[source]
Parameters:
  • script_dir – Relative path to the Scripts directory
  • htmlPath – Relative path to the html output path
Returns:

a list of dictionaries with fields: - file - what is the input R file - outputFile - there to put the output html file - param - parsed yaml params
wbuild.utils.parseYAMLHeader(filepath)[source]
Parameters:filepath – path to the file
Returns:String representation of the YAML header in the file, including inter-document framing (“—”)
wbuild.utils.parseYamlParams(header, f)[source]
Parameters:
  • header – String form of YAML header
  • f – Filename of a file from where the header was parsed
Returns:

Parameters dictionary parsed from the header; None if parsing errors occured
wbuild.utils.pathsepsToUnderscore(systemPath, dotsToUnderscore=False, trimPrefix=True)[source]

Convert all system path separators and dots to underscores. Product is used as a unique ID for rules in scanFiles.py or the output HTML files :param systemPath: path to convert in :param dotsToUnderscore: if the dot should be converted as well. Defaults to false :return: path string with converted separators

wbuild.utils.wbuildVersionIsCurrent()[source]

Read wBuild version from .wBuild/.version and compare it to wbuild module version from pckg mngr. :return: True if wBuild up-to-date, False if not

wbuild.utils.writeWbuildVersion()[source]

Write wBuild version to .wBuild/.version

HTML output index creation (wbuild.createIndex)

wbuild.createIndex.ci(scriptsPath=None, index_name=None)[source]

Write HTML index file

Parameters:
  • scriptsPath – relative scripts path. If not specified, use the default scripts path from the config.
  • index_name – prefix of the index file name <index_name>_index.html
wbuild.createIndex.createIndexRule(scriptsPath=None, index_name=None, wbData=None, mdData=None)[source]

Create the input and output files necessary for an HTML index rule.

Parameters:
  • scriptsPath – relative scripts path. If not specified, use the default scripts path from the config.
  • index_name – prefix of the index file name <index_name>_index.html
  • wbData – wBuild rule data from parsed R scripts
  • mdData – wBuild rule data from parsed markdown files
Returns:

  • inputFiles - list of output HTML files from the scriptsPath, comprising the input of the index rule
  • indexPath - index html file name, equates to the output
  • graphPath - dependency graph image file name for HTML template (graph is needs to be written to this file)
  • readmePath - readme HTML name for HTML template (takes readme from the scriptsPath)
wbuild.createIndex.getRecentMenu()[source]

Support recently edited files list to the HTML web output.

Returns:HTML string: “Recently viewed” menu contents
wbuild.createIndex.writeDepSVG(graphPath=None)[source]

Search for rule graph. If path not specified in config, take default dep.svg in snakeroot path

wbuild.createIndex.writeIndexHTMLMenu(scriptsPath=None, index_name=None)[source]

Scan for files involved in the current HTML rendering and fill the HTML quick access toolbar correspondingly

wbuild.createIndex.writeReadme(readmePath)[source]

Create readme file output for html template readmePath: html readme path

wbuild.createIndex.writeSubMenu(top, wbData, level)[source]

Recursive call to construct the dropdown list and hover-over side-menus in it adhereing to a “top” toolbar category.

Parameters:
  • top – “top” toolbar directory to be appointed to
  • wbData – wb relevant data of all scanned files
  • level – deepness of the current submenu (first dropdown list, then hover-over side-menus in the html)
Returns:

deeply constructed dropdown list of the top toolbar category as an HTML string