Convert CONTRIBUTE to rst and add to the Docs.

Let's see if GitHub is happy with this...
This commit is contained in:
Florian Festi 2018-09-11 17:42:08 +02:00
parent 57fbda35e0
commit ef30589f8f
2 changed files with 27 additions and 15 deletions

View File

@ -1,4 +1,5 @@
# Contributing to Boxes.py Contributing to Boxes.py
============================
You are thinking about contributing to Boxes.py? That's great! You are thinking about contributing to Boxes.py? That's great!
Boxes.py is designed to be re-used and extended. Boxes.py is designed to be re-used and extended.
@ -11,7 +12,8 @@ Most of them should be just general best practises and not be
surprising. Don't worry if you find them too complicated. It is OK surprising. Don't worry if you find them too complicated. It is OK
leave the final touch to someone else. leave the final touch to someone else.
## Writing code for Boxes.py Writing code for Boxes.py
-----------------------------
You will often be compelled to just do a quick thing that will solve You will often be compelled to just do a quick thing that will solve
your immediate needs. That's fine. But nevertheless it is often worth your immediate needs. That's fine. But nevertheless it is often worth
@ -28,16 +30,20 @@ or are going to finish it on your own.
* Please fork the repository at GitHub before getting started * Please fork the repository at GitHub before getting started
* Start with creating separate branches for each of your new generators or features * Start with creating separate branches for each of your new generators or features
* You can merge them into your master branch to have them all in one place
* Please continue your work in the branches and repeatedly merge them to master * You can merge them into your master branch to have them all in one place
* Please continue your work in the branches and repeatedly merge them to master
* Before submitting a pull request intened to go upstream have clean patches that are self contained and error free * Before submitting a pull request intened to go upstream have clean patches that are self contained and error free
* Re-order and squash patches with *git rebase -i*
* The patches should contaning meaningful changes and not * Re-order and squash patches with *git rebase -i*
(nessesarily) reflect how the code was created * The patches should contaning meaningful changes and not (nessesarily) reflect how the code was created
* Rebase your branch to the current master branch * Rebase your branch to the current master branch
* Be prepared that you code may get reworked before being merged upstream * Be prepared that you code may get reworked before being merged upstream
* Submit a pull request in GitHub based on your feature branch * Submit a pull request in GitHub based on your feature branch
* Describe the status of the patch set and your intentions with it in the pull request message
* Describe the status of the patch set and your intentions with it in the pull request message
If you want to discuss your idea open a ticket describing it and ask If you want to discuss your idea open a ticket describing it and ask
questions there. This is encouraged even if you think you know what questions there. This is encouraged even if you think you know what
@ -48,7 +54,8 @@ If you want feed back on you code feel free to open a PR. State that
this is work in progress in the PR message. It's OK if it does not this is work in progress in the PR message. It's OK if it does not
follow the guide lines (yet). follow the guide lines (yet).
### Writing new Generators Writing new Generators
......................
Writing new generators is the most straight forward thing to do with Writing new generators is the most straight forward thing to do with
Boxes.py. Here are some guidelines that make it easier to get them added: Boxes.py. Here are some guidelines that make it easier to get them added:
@ -60,7 +67,8 @@ Boxes.py. Here are some guidelines that make it easier to get them added:
* For more complicated generators there can be multiple patches - * For more complicated generators there can be multiple patches -
each adding another feature each adding another feature
## Improving the Documentation Improving the Documentation
---------------------------
Boxes.py comes with Sphinx based documentation that is in large parts Boxes.py comes with Sphinx based documentation that is in large parts
generated from the doc strings in the code. Nevertheless documentation generated from the doc strings in the code. Nevertheless documentation
@ -73,7 +81,8 @@ To get the docs updated the docs need to be build with *make html* in
branch. That's a bit tricky. Feel free to not even bother with this branch. That's a bit tricky. Feel free to not even bother with this
and just submit the changes to the sources or just open a ticket. and just submit the changes to the sources or just open a ticket.
## Improving the User Interface Improving the User Interface
----------------------------
Coming up with good names and good descriptions is hard. Often writing Coming up with good names and good descriptions is hard. Often writing
a new generator is much easier than coming up with a good name for it a new generator is much easier than coming up with a good name for it
@ -88,7 +97,8 @@ use or just more detailed descriptions. If you are interested in
writing some please open a ticket. Your text does not have to be writing some please open a ticket. Your text does not have to be
perfect. We can work on it together. perfect. We can work on it together.
## Reporting bugs Reporting bugs
--------------
If you encounter issues with Boxes.py, please open a ticket at If you encounter issues with Boxes.py, please open a ticket at
GitHub. Please provide all information necessary to reproduce the GitHub. Please provide all information necessary to reproduce the
@ -98,7 +108,8 @@ description. Otherwise it can be helpful to attach the resulting SVG,
a screen shot or the error message. Add a "bug" tag to draw additional a screen shot or the error message. Add a "bug" tag to draw additional
attention. attention.
## Suggesting new generators or features Suggesting new generators or features
-------------------------------------
If you have an idea for a new generator or feature please open a If you have an idea for a new generator or feature please open a
ticket. Give some short rational how or where you would use such a ticket. Give some short rational how or where you would use such a

View File

@ -14,6 +14,7 @@ Contents:
README README
install install
usermanual usermanual
CONTRIBUTE.rst
apiintro apiintro
Boxes Boxes
edges edges