Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
133 lines (79 sloc) 3.47 KB

First-time setup

  • You need to install Python 3 which is required for building docs.

For example, Python 3.7.

Then, create and activate a virtual environment. And install tox.

  1. Please, identify yourself:

    $ git config --global user.name "firstname lastname"
    $ git config --global user.email yourname@example.com
    
  • Use the address bound to your GitHub account so that the commits would be linked to your profile.
  1. Choose an editor for Git:

    $ git config --global core.editor vim
    
  • Create and log in to a GitHub account

  • Fork Cheroot to your GitHub account by clicking the Fork button

  • Clone your fork locally:

    $ git clone https://github.com/{username}/cheroot
    $ cd cheroot
    
  • Also, you can clone fork using ssh:

    $ git clone git@github.com:{username}/cheroot.git
    $ cd cheroot
    
  • To create a new branch and switch to it:

    $ git checkout -b patch/some_fix
    

Write your code

Once you finished coding, you are recommended to do the following steps:

  • Run tests with tox

Run one test with Python3.6:

$ tox -e py36 -- cheroot/test/test_name.py

`tox` — Run all tests using the Python version where python command currently points to which is specified in tox settings:

envlist = python
minversion = 3.5.3

Run linters and all tests against several Python interpreters:

$ tox -e pre-commit,py27,py37  # etc.

Building the docs

To build the docs from a checked out source, run:

$ tox -e build-docs

Open the documentation:

.. tabs::

   .. tab:: GNU/linux

      $ xdg-open build/html/index.html

   .. tab:: macOS

      $ open build/html/index.html

   .. tab:: Windows

      Please, open build/html/index.html in your browser.

Also, one can serve docs using a built-in static files server. This is preferable because of possible CSRF issues.:

$ python3 -m http.server --directory build/html/ 8000

After that, you can open http://localhost:8000/ in your browser.

Read more about Sphinx.