1.. _contributing:
2
3Contributing to bpython
4=======================
5
6Thanks for working on bpython!
7
8On the `GitHub issue tracker`_ some issues are labeled bite-size_ -
9these are particularly good ones to start out with.
10
11See our section about the :ref:`community` for a list of resources.
12
13`#bpython <irc://irc.oftc.net/bpython>`_ on OFTC is particularly useful,
14but you might have to wait for a while to get a question answered depending on
15the time of day.
16
17Getting your development environment set up
18-------------------------------------------
19
20bpython supports Python 3.6 and newer. The code is compatible with all
21supported versions.
22
23Using a virtual environment is probably a good idea. Create a virtual
24environment with
25
26.. code-block:: bash
27
28    # determines Python version used
29    $ virtualenv bpython-dev
30    # necessary every time you work on bpython
31    $ source bpython-dev/bin/activate
32
33Fork bpython in the GitHub web interface, then clone the repo:
34
35.. code-block:: bash
36
37    $ git clone git@github.com:YOUR_GITHUB_USERNAME/bpython.git
38    # or "git clone https://github.com/YOUR_GITHUB_USERNAME/bpython.git"
39
40Next install your development copy of bpython and its dependencies:
41
42.. code-block:: bash
43
44    $ cd bpython
45    # install bpython and required dependencies
46    $ pip install -e .
47    # install optional dependencies
48    $ pip install watchdog urwid
49    # development dependencies
50    $ pip install sphinx pytest
51    <modify a file in some way>
52    # this runs your modified copy of bpython!
53    $ bpython
54
55.. note::
56
57    Many requirements are also available from your distribution's package
58    manager. On Debian/Ubuntu based systems, the following packages can be
59    used:
60
61    .. code-block:: bash
62
63        $ sudo apt install python3-greenlet python3-pygments python3-requests
64        $ sudo apt install python3-watchdog python3-urwid
65        $ sudo apt install python3-sphinx python3-pytest
66
67    You also need to run `virtualenv` with `--system-site-packages` packages, if
68    you want to use the packages provided by your distribution.
69
70.. note::
71
72    Installation of some dependencies with ``pip`` requires Python headers and
73    a C compiler. These are also available from your package manager.
74
75    .. code-block:: bash
76
77        $ sudo apt install gcc python3-dev
78
79As a first dev task, I recommend getting `bpython` to print your name every
80time you hit a specific key.
81
82To run tests from the bpython directory:
83
84.. code-block:: bash
85
86    $ pytest
87
88
89Building the documentation
90--------------------------
91
92The documentation is included in the bpython repository. After
93checking out the bpython repository and installing `sphinx` as described in
94the previous step, you can run the following command in your checkout of the
95repository to build the documentation:
96
97.. code-block:: bash
98
99    $ make -C doc/sphinx html
100
101Afterwards you can point your browser to `doc/sphinx/build/html/index.html`.
102Don't forget to recreate the HTML after you make changes.
103
104Hacking on the site or theme
105----------------------------
106
107The site (and its theme as well) is stored in a separate repository and built
108using pelican. To start hacking on the site you need to start out with a
109checkout and probably a virtual environment:
110
111.. code-block:: bash
112
113    $ virtualenv bpython-site-dev
114    $ source bpython-site-dev/bin/activate
115    $ pip install pelican
116
117Fork bsite and bsite-theme in the GitHub web interface, then clone the
118repositories:
119
120.. code-block:: bash
121
122    $ git clone git@github.com:YOUR_GITHUB_USERNAME/bsite.git
123    $ git clone git@github.com:YOUR_GITHUB_USERNAME/bsite-theme.git
124
125Next you can fiddle around in the source files. If you want to build the site
126you activate your virtualenv and tell pelican to generate the site with the
127included configuration file.
128
129.. code-block:: bash
130
131    $ source bpython-site-dev/bin/activate
132    # if you want to fiddle on the text of the site otherwise go into
133    # bsite-theme
134    $ cd bsite
135    # if you checked out the theme in a different place, use that path
136    $ pelican -t ../bsite-theme -s pelicanconf.py
137
138After this you can open the `output/index.html` in your favourite browser and
139see if your changes had an effect.
140
141.. _GitHub issue tracker: https://github.com/bpython/bpython/issues
142.. _bite-size: https://github.com/bpython/bpython/labels/bitesize
143