Contributing

Basic guidelines

  1. Fork the project from https://github.com/mondeja/pug-mixins
  2. Download the source code from github with git clone https://github.com/<your-user>/pug-mixins.git or manually from https://github.com/<your-user>/pug-mixins/archive/master.zip.
  3. Install python dependencies with pip install -r requirements.txt.
  4. Fix a bug or create a new feature (and write tests if this is your case).
  5. Run tests with make tests or pytest test. If something is broken, fix it.
  6. Write documentation for this new features if necessary and build it. See doc/ – Writing documentation.
  7. Commit your changes and pull git pull origin master.
  8. Make a pull request from the github interface. See CI testing for your pull request. If something is broken, fix it and restart the pull request.

See also

Development status

Project directories tree

  • src: Source code of the project. All mixins are catalogued by folders according to their use, not by html tags.
  • doc: Project documentation. See doc/ – Writing documentation.
  • test: Project tests wrote with pytest. See test/ – Testing.
  • scripts: Useful scripts. You can see here a python script called doc_prebuild.py that loads source code mixins and insert on documentation through jinja2 renderization.

doc/ – Writing documentation

Documentation for each new module must be located at doc/source/_templates/. This folder has the same directories structure of src/. If you see the existing templates you will observe that mixins source code are included by their name, replacing - caracters with _ and enclosed by double { and } caracters.

Build steps

The script located at scripts/prebuild_doc.py render all source code mixins in their respective files. Execute it normally or use make doc-prebuild (Linux/Mac users).

Generated output files will be located at doc/source/user_guide/modules/. This files need to be referenced from doc/source/user_guide/reference.rst toctrees.

So the build documentation process involves 2 steps, first prebuild with previously explained script and the build process with sphinx. You can execute this 2 steps secuentially running make doc-build.

Mixins structure

Please, respect documentation structure for each mixin. These must include, at least, the next information in order:

  • Source code of the mixin.
  • Mixin documentation (description, attributes…)
  • Usage example with:
    • Input example.
    • HTML output of that example.
    • Renderization output.