Skip to content

Latest commit

 

History

History
62 lines (42 loc) · 2.7 KB

CONTRIBUTING.md

File metadata and controls

62 lines (42 loc) · 2.7 KB
Raw

Information for Contributors

Development Environment

Start hacking

git clone -b testing git@github.com:DARIAH-DE/Topics
cd Topics
mkvirtualenv Topics      # if you use virtualenvwrapper
workon Topics            # if you use virtualenvwrapper
pip install -r requirement-dev.txt

Releasing / Pushing to Master

The testing branch is the integration branch for current developments. The master branch should always contain the latest stable version.

Pushing to master is protected, you can only push heads that have an "green" status from the integration build. To do so, do the following (from a clean working copy):

  1. Prepare everything in testing. Don't forget to tune the version number.
  2. Merge testing into master. Use --no-ff to make sure we get a merge commit: git checkout master; git merge --no-ff testing
  3. if there are conflicts, resolve them and commit (to master)
  4. now, fast-forward-merge master into testing: git checkout testing; git merge master. testing and master should now point to the same commit.
  5. push testing. This will trigger the integration build, which will hopefully work out fine.
  6. when the build has successfully finished, push master.

If something goes wrong, git reset --hard master origin/master and try again.

Documentation

The documentation is built using Sphinx. The following files influence the docs:

  • index.rst contains the landing page with the table of contents. Here, all files should be linked.
  • *.ipynb for tutorials etc. can be linked from the index file
  • README.md and CONTRIBUTING.md will also be included
  • Docstrings in the modules will be included
  • docs/**/* may contain additional files
  • conf.py contains sphinx configuration
  • setup.py contains version numbers etc.

Documentation formats

Standalone documentation files can be written in one of the following formats:

Docstrings should follow Google conventions, this is supported by Napoleon.

Build the documentation

Run python setup.py build_sphinx -a, which will create the documentation tree in build/sphinx/html.

After adding another module

Run sphinx-apidoc -M -e -o docs/gen dariah_topics to add a documentation stub to docs/gen.