Skip to content

Commit f7780ab

Browse files
JelteFJelteF
committed
Move CONTRIBUTIG to docs
1 parent 73d902e commit f7780ab

File tree

2 files changed

+101
-46
lines changed

2 files changed

+101
-46
lines changed

Diff for: ‎CONTRIBUTING.md

+1-38
Original file line numberDiff line numberDiff line change
@@ -1,38 +1 @@
1-
### How to contribute
2-
3-
#### Some tips
4-
5-
- Install all the development dependencies by running `pip install -r
6-
dev_requirements.txt` when you are in your local fork.
7-
- To learn how to squash commits, read this
8-
[blog](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html).
9-
Ignore the word of caution, since that only applies to main repositories on
10-
which people base their own work.
11-
You can do this when you have a couple of commits that are basically fix
12-
this typo/bug in the code I created for this same pull request.
13-
- Look at the code that is already there when creating something new, for
14-
instance the classes for tables.
15-
16-
17-
#### Some rules
18-
There are just two things you really need to do:
19-
- Follow the **PEP8** style guide and make sure it passes pyflakes.
20-
(You can use flake8 with the pep8-naming extension to test these both)
21-
- Run the `testall.sh` script before making a pull request to check if you
22-
didn't break anything.
23-
24-
If you don't do these two things Travis will catch you anyway.
25-
26-
27-
If you want you can also do these things and they are appreciated:
28-
29-
- If you add something new, show it off with an **example**.
30-
- If you add new arguments, function or classes, add them to
31-
`tests/args.py` without forgetting to name the arguments. That way I will know when the external API is changed
32-
later on.
33-
- If you fix something, add a **test** so it won't break again.
34-
- Add your addition, change or fix to the **changelog** so it will be mentioned
35-
in the next release.
36-
37-
It would be nice if you would do these things. But to be fair, I don't do it
38-
all the time either.
1+
See the documentation: https://jeltef.github.io/PyLaTeX/latest/contributing.html

Diff for: ‎docs/source/contributing.rst

+100-8
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,70 @@
11
How to contribute
22
=================
33

4-
This section needs to be filled. For now, see the `CONTRIBUTING.md
5-
<https://github.com/JelteF/PyLaTeX/blob/master/CONTRIBUTING.md>`_ file in the
6-
git repository.
4+
.. highlight:: bash
5+
6+
First of all, if anything is incorrect or something is missing on this page (or
7+
any other for that matter), please send in a pull request. It is important that
8+
setting up the development environment is as painless as possible.
9+
10+
Setting up the development environment
11+
--------------------------------------
12+
Unfortunately there are quite some steps involved in setting up a development
13+
environment. If you don't want to do this and know how Vagrant works, see the
14+
bottom of this section on how to use that instead.
15+
16+
OS specific dependencies
17+
~~~~~~~~~~~~~~~~~~~~~~~~
18+
Some dependencies are OS specific. Ofcourse you need to have LaTeX installed,
19+
but that also comes in some different packages on most systems.
20+
21+
For Ubuntu and other Debian based systems::
22+
23+
sudo apt-get install python3 python3-dev virtualenv \
24+
texlive-pictures texlive-science texlive-latex-extra \
25+
imagemagick
26+
27+
28+
Getting the source code
29+
~~~~~~~~~~~~~~~~~~~~~~~
30+
You need your own fork of the Github repository by using the Github fork
31+
button. You will then need to clone your version of the repo using the normal
32+
way, something like this::
33+
34+
git clone [email protected]:YourUserName/pylatex
35+
cd pylatex
36+
37+
Make your own branch for your specific feature or fix (don't do this just on
38+
master)::
39+
40+
git checkout -b your-nice-feature
41+
42+
43+
Python environment setup
44+
~~~~~~~~~~~~~~~~~~~~~~~~
45+
This method will use a virtual environment, this is the easiest way to get all
46+
the dependencies.
47+
48+
1. Create a virtualenv by running::
49+
50+
virtualenv venv -p python3
51+
52+
2. Activate it by running (you should do this whenever you start working on
53+
your changes)::
54+
55+
. venv bin activate
56+
57+
3. Install all the development dependencies inside the virtual environment by
58+
running::
59+
60+
pip install -r dev_requirements.txt
761

862
Vagrant support
9-
---------------
10-
If you don't want to manually setup a suitable development environment in
11-
order to contribute, PyLaTeX comes with a ready-made Vagrantfile. Vagrant
12-
will launch and configure a small virtual machine with all necessary
13-
tools for you, so that you can start working with PyLaTeX right away.
63+
~~~~~~~~~~~~~~~
64+
This might be an easier way to obtain a development environment, but the script
65+
is not very well maintained and might not work anymore. If everything goes as
66+
planned Vagrant will launch and configure a small virtual machine with all
67+
necessary tools for you, so that you can start working with PyLaTeX right away.
1468

1569
With Vagrant already installed, you can start the virtual machine with
1670
``$ vagrant up`` and then use ``$ vagrant ssh`` to ssh into it. Your source
@@ -19,3 +73,41 @@ To run all unit tests and build the documentation run
1973
``$ ./testall.sh -p python3 -c`` from that directory.
2074

2175
You can download or read more about Vagrant on https://www.vagrantup.com/.
76+
77+
Some tips before starting
78+
-------------------------
79+
1. Look at the code that is already there when creating something new, for
80+
instance the classes for tables.
81+
2. To learn how to squash commits, read this `blog
82+
<http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html>`_.
83+
Ignore the word of caution, since that only applies to main repositories on
84+
which people base their own work. You can do this when you have a couple of
85+
commits that could be merged together. This mostly happens when you have
86+
commits that fix a typo or bug you made in a pull request and you fix that
87+
in a new commit.
88+
89+
Some rules
90+
----------
91+
There are two things that are needed for every pull request:
92+
93+
1. Run the ``testall.sh`` script before making a pull request to check if you
94+
didn't break anything.
95+
2. Follow the **PEP8** style guide and make sure it passes pyflakes (this is
96+
also tested with the ``testall.sh`` script).
97+
98+
These are also tested for by Travis, but please test them yourself as well.
99+
100+
Depending on your type of changes some other things are needed as well.
101+
102+
1. If you add new arguments, function or classes, add them to
103+
``tests/args.py`` without forgetting to name the arguments. That way it is
104+
easy to see when the external API is changed in the future.
105+
2. Change docstrings when necessary. For instance when adding new arguments or
106+
changing behaviour.
107+
3. If you fix something, add a **test** so it won't break again.
108+
4. If your change is user facing, add it to the **changelog** so it will be
109+
mentioned in the next release. Its location is at
110+
``docs/source/changelog.rst``.
111+
5. If you add something new, show it off with an **example**. If you don't do
112+
this, I will probably still merge your pull request, but it is always nice
113+
to have examples of features.

0 commit comments

Comments
 (0)