Skip to content

Latest commit

 

History

History
145 lines (102 loc) · 5.48 KB

CONTRIBUTING.md

File metadata and controls

145 lines (102 loc) · 5.48 KB

Contributing Guide

semantic-release: angular

Thank you for contributing to GraphicDocs!

Before contributing, please take a moment to read through this document. This guide documents the standards, tooling, and processes that go into the CI/CD pipeline.

Table of Contents

Code of Conduct

Please help keep this project open and inclusive. Refer to the Graphic Art Quest Common Code of Conduct before your first contribution.

How can I Contribute?

Submit Issues

Bug Reports: Be as detailed as possible, and fill out all information requested in the bug report template.

For security related issues, see the security policy.

Documentation Requests: Is something unclear in the documentation or the API? Submit a documentation change request! Be as detailed as possible. If you have the question, chances are someone else will also who isn't as willing to speak up as you are. If you want to do it yourself, see the documentation guidelines for instructions.

Propose New Tags

New tag requests are welcome. Please ask before embarking on any significant undertaking (e.g. implementing a new tag, major code refactoring), otherwise you risk wasting time on something that might not fit well with the project. Do this by opening an issue for the proposal.

Submit a Pull Request

Good pull requests are outstanding help. They should remain focused in scope and avoid unrelated commits.

To submit a pull request,

  1. Fork and clone the repository
  2. Create a branch for your edits
  3. Make sure your work follows the commits guidance

Commits

All commits must follow the Wayfind Entertainment Common Commit Guidance guidelines, types, and scopes.

The following custom scopes are allowed:

  • Any docstring tag (e.g. author, example, param, throws)
  • One of the key source files:
    • core
    • hooks
    • parser
  • A template:
    • grahpic_md

Changes to how tags are parsed from the docstring functions should use the relevant tag scope. Use parser for changes to the parsing engine itself.

Development

This project requires you to have Python installed.

Local Installation

git clone https://github.com/GraphicArtQuest/GraphicDocs.git
cd GraphicDocs

After installing, you should run the test script to verify everything works without runtime errors before you start modifying.

Project Structure

├── docs
│   ├── api
│   ├── tags
│   ├── templates
|   └── core.md
├── src
│   ├── parse_docstring_functions
│   ├── plugins
│   ├── templates
|   ├── core.py
|   ├── hooks.py
|   └── parser.py
├── tests
|   ├── core
|   └── parser
  • docs:
    • api: Automatically generated with GraphicDocs itself; make no changes by hand here
    • tags: Detailed examples on use of each docstring tag
    • templates: Detailed instructions on how to use the built-in templates
    • core.md: Detailed instructions on how to use all the features within the core engine
  • src: contains all source files
    • parse_docstring_functions: individual tag parsing functions, split up for modularity
    • plugins: built-in plugins that ship with GraphicDocs
    • templates: built-in templates that ship with GraphicDocs
    • core.md: The main code that directs the parsing, organizing, and creation of code documentation
    • hooks.py: A system of filters and actions that the core, plugins, and templates use to extend functionality
    • parser.py: The engine behind parsing docstrings into a usable dictionary object
  • tests: The unittest scripts used to verify the core, hooks, and parser work as designed

Testing

This project uses the unittest suite. To run all tests, open the console and enter:

python test.py

Documentation

Most of the project's documentation is (ironically) created by hand in order to guide users through detailed steps of how to setup and configure the tool. However, the API documentation itself gets created by running the following console command:

python docs.py

Building

There is currently no build step in this project.