Skip to content

Commit f5f95ef

Browse files
Valentijnleandrotoledo
Valentijn
authored and
leandrotoledo
committed
Documentation (python-telegram-bot#350)
* Small fixes to documentation and add myself to AUTHORS. * Rework CONTRIBUTIONS.rst Use code-blocks instead of literals, change headings for portability and use a relative link to AUTHORS instead of linking to a specific copy.
1 parent 04a871a commit f5f95ef

File tree

5 files changed

+70
-50
lines changed

5 files changed

+70
-50
lines changed

‎.github/CONTRIBUTING.rst

Lines changed: 64 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,41 @@
11
How To Contribute
2-
=================
2+
===================
33

44
Every open source project lives from the generous help by contributors that sacrifice their time and ``python-telegram-bot`` is no different. To make participation as pleasant as possible, this project adheres to the `Code of Conduct`_ by the Python Software Foundation.
55

66
Setting things up
7-
-----------------
7+
-------------------
88

99
1. Fork the ``python-telegram-bot`` repository to your GitHub account.
1010

1111
2. Clone your forked repository of ``python-telegram-bot`` to your computer:
1212

13-
``$ git clone https://github.com/<your username>/python-telegram-bot``
13+
.. code-block:: bash
1414
15-
``$ cd python-telegram-bot``
15+
$ git clone https://github.com/<your username>/python-telegram-bot
16+
$ cd python-telegram-bot
1617
1718
3. Add a track to the original repository:
1819

19-
``$ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot``
20+
.. code-block:: bash
21+
22+
$ git remote add upstream https://github.com/python-telegram-bot/python-telegram-bot
2023
2124
4. Install dependencies:
2225

23-
``$ pip install -r requirements.txt -r requirements-dev.txt``
26+
.. code-block:: bash
27+
28+
$ sudo pip install -r requirements.txt -r requirements-dev.txt
2429
2530
2631
5. Install pre-commit hooks:
2732

28-
``$ pre-commit install``
33+
.. code-block:: bash
34+
35+
$ pre-commit install
2936
3037
Finding something to do
31-
-----------------------
38+
###################
3239

3340
If you already know what you'd like to work on, you can skip this section.
3441

@@ -37,7 +44,7 @@ If you have an idea for something to do, first check if it's already been filed
3744
Another great way to start contributing is by writing tests. Tests are really important because they help prevent developers from accidentally breaking existing code, allowing them to build cool things faster. If you're interested in helping out, let the development team know by posting to the `developers' mailing list`_, and we'll help you get started.
3845

3946
Instructions for making a code change
40-
-------------------------------------
47+
####################
4148

4249
The central development branch is ``master``, which should be clean and ready for release at any time. In general, all changes should be done as feature branches based off of ``master``.
4350

@@ -47,13 +54,12 @@ Here's how to make a one-off code change.
4754

4855
2. **Create a new branch with this name, starting from** ``master``. In other words, run:
4956

50-
``$ git fetch upstream``
51-
52-
``$ git checkout master``
53-
54-
``$ git merge upstream/master``
57+
.. code-block:: bash
5558
56-
``$ git checkout -b your-branch-name``
59+
$ git fetch upstream
60+
$ git checkout master
61+
$ git merge upstream/master
62+
$ git checkout -b your-branch-name
5763
5864
3. **Make a commit to your feature branch**. Each commit should be self-contained and have a descriptive commit message that helps other developers understand why the changes were made.
5965

@@ -75,19 +81,27 @@ Here's how to make a one-off code change.
7581

7682
- Before making a commit ensure that all automated tests still pass:
7783

78-
``$ make test``
84+
.. code-block::
85+
86+
$ make test
7987
8088
- To actually make the commit (this will trigger tests for yapf, lint and pep8 automatically):
8189

82-
``$ git add your-file-changed.py``
90+
.. code-block:: bash
91+
92+
$ git add your-file-changed.py
93+
94+
- yapf may change code formatting, make sure to re-add them to your commit.
8395

84-
- yapf may change code formatting, make sure to re-add them to your commit.
96+
.. code-block:: bash
8597
86-
``$ git commit -a -m "your-commit-message-here"``
98+
$ git commit -a -m "your-commit-message-here"
8799
88100
- Finally, push it to your GitHub fork, run:
89101

90-
``$ git push origin your-branch-name``
102+
.. code-block:: bash
103+
104+
$ git push origin your-branch-name
91105
92106
4. **When your feature is ready to merge, create a pull request.**
93107

@@ -107,66 +121,67 @@ Here's how to make a one-off code change.
107121

108122
- Resolve any merge conflicts that arise. To resolve conflicts between 'your-branch-name' (in your fork) and 'master' (in the ``python-telegram-bot`` repository), run:
109123

110-
``$ git checkout your-branch-name``
111-
112-
``$ git fetch upstream``
124+
.. code-block:: bash
113125
114-
``$ git merge upstream/master``
115-
116-
``$ ...[fix the conflicts]...``
117-
118-
``$ ...[make sure the tests pass before committing]...``
119-
120-
``$ git commit -a``
121-
122-
``$ git push origin your-branch-name``
126+
$ git checkout your-branch-name
127+
$ git fetch upstream
128+
$ git merge upstream/master
129+
$ ...[fix the conflicts]...
130+
$ ...[make sure the tests pass before committing]...
131+
$ git commit -a
132+
$ git push origin your-branch-name
123133

124134
- At the end, the reviewer will merge the pull request.
125135

126136
6. **Tidy up!** Delete the feature branch from both your local clone and the GitHub repository:
127137

128-
``$ git branch -D your-branch-name``
138+
.. code-block:: bash
129139
130-
``$ git push origin --delete your-branch-name``
140+
$ git branch -D your-branch-name
141+
$ git push origin --delete your-branch-name
131142
132143
7. **Celebrate.** Congratulations, you have contributed to ``python-telegram-bot``!
133144

134145
Style commandments
135-
==================
146+
---------------------
136147

137148
Specific commandments
138-
---------------------
149+
#####################
139150

140151
- Avoid using "double quotes" where you can reasonably use 'single quotes'.
141152

142153
AssertEqual argument order
143-
--------------------------
154+
######################
144155

145156
assertEqual method's arguments should be in ('actual', 'expected') order.
146157

147158
Properly calling callables
148-
--------------------------
159+
#######################
149160

150161
Methods, functions and classes can specify optional parameters (with default
151162
values) using Python's keyword arg syntax. When providing a value to such a
152-
callable we prefer that the call also uses keyword arg syntax. For example::
163+
callable we prefer that the call also uses keyword arg syntax. For example:
153164

154-
# GOOD
155-
f(0, optional=True)
165+
.. code-block:: python
156166
157-
# BAD
158-
f(0, True)
167+
# GOOD
168+
f(0, optional=True)
169+
170+
# BAD
171+
f(0, True)
159172
160173
This gives us the flexibility to re-order arguments and more importantly
161174
to add new required arguments. It's also more explicit and easier to read.
162175

163176
Properly defining optional arguments
164-
------------------------------------
177+
########################
178+
179+
It's always good to not initialize optional arguments at class creation,
180+
instead use ``**kwargs`` to get them. It's well known Telegram API can
181+
change without notice, in that case if a new argument is added it won't
182+
break the API classes. For example:
165183

166-
It's always good to not initialize optional arguments at class creation,
167-
instead use ``**kwargs`` to get them. It's well known Telegram API can
168-
change without notice, in that case if a new argument is added it won't
169-
break the API classes. For example::
184+
.. code-block:: python
170185
171186
# GOOD
172187
def __init__(self, id, name, **kwargs):
@@ -183,4 +198,4 @@ break the API classes. For example::
183198
.. _`PEP 8 Style Guide`: https://www.python.org/dev/peps/pep-0008/
184199
.. _`Google Python Style Guide`: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
185200
.. _`Google Python Style Docstrings`: http://sphinx-doc.org/latest/ext/example_google.html
186-
.. _AUTHORS.rst: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/AUTHORS.rst
201+
.. _AUTHORS.rst: ../AUTHORS.rst

‎AUTHORS.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ The following wonderful people contributed directly or indirectly to this projec
2525
- `Rahiel Kasim <https://github.com/rahiel>`_
2626
- `Shelomentsev D <https://github.com/shelomentsevd>`_
2727
- `sooyhwang <https://github.com/sooyhwang>`_
28+
- `Valentijn <https://github.com/Faalentijn>`_
2829
- `wjt <https://github.com/wjt>`_
2930

3031
Please add yourself here alphabetically when you submit your first pull request.

‎CHANGES.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
==============
2+
Changes
3+
==============
14
**2016-07-12**
25

36
*Released 4.3.4*

‎docs/Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,4 +189,4 @@ xml:
189189
pseudoxml:
190190
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
191191
@echo
192-
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
192+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

‎docs/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ Welcome to Python Telegram Bot's documentation!
77
===============================================
88

99
Contents:
10+
telegram
1011

1112
.. toctree::
1213
:maxdepth: 2

0 commit comments

Comments
 (0)