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.
Fork the wbuild repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/wbuild.git
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
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
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.
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
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:
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.
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
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
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
Script mapping (wbuild.autolink
)¶
See also the overview of this feature