Tutorial¶
This tutorial will get you started in using this template to create a python project.
Step 1: Install Cookiecutter¶
You can use your system python to start your python project,
or use a virtualenv
. This tutorial will use the virtualenv
method.
First, you need to create and activate your virtualenv for your python project. Use your favorite method, or create a virtualenv for your project like this:
virtualenv -p python2.7 ~/.virtualenvs/your_python_project
Here, your_python_project
is the name of the python project that
you’ll create.
Note
You can use this template on an existing project !
Activate your environment:
source ~/.virtualenvs/serverdoc/bin/activate
You can got back anytime to the system python by typing:
deactivate
On Windows, activate it like this. You may find that using a Command Prompt window works better than gitbash.
> \path\to\env\Scripts\activate
On both platform, install cookiecutter with pip:
pip install cookiecutter
Step 2: Generate your project¶
Now it’s time to generate your python project.
Use cookiecutter, pointing it at the cookiecutter-python repo:
cookiecutter https://gitlab.com/ericdevost/cookiecutter-python.git
Note
If you want to use cookiecutter-python over an existing project,
you can add the -f
flag to the above command, meaning to
not fail if the project exist.
You’ll be asked to enter values to set your project up. If you don’t know what to enter, stick with the defaults. You can find a detailed documentation on the values in the Prompts section of this documentation.
Step 3: Build your python project locally¶
Once your project had been set up with cookiecutter, you can install the needed dependencies for the documentation.
$ python -m pip install -r requirements/_docs.txt
You are now ready to build your documentation locally with one simple command:
$ python setup.py docs
Your newly built documentation will be accessible in the build/docs/html
folder.
Step 4: Write your doc¶
Make any changes, corrections or additions to your documentation. You can build
it anytime by typing python setup.py docs
and see the changes in your
browser. Once you are satisfied, it’s time to publish your documentation
Step 5: Create a GitLab Repo¶
Go to your GitLab account and create a new repo i. Name it after
your project name
, where your project
matches the project_name
you entered when you ran cookiecutter.
Step 6: Activate your GitLab repo¶
On your computer, enter your newly created project folder
, where
project folder
is the project_name
you entered when you ran
cookiecutter, then activate your repository:
cd ``project_name``
git init .
git add .
git commit -m "Initial skeleton."
git remote add origin your-gitla-repo
git push -u origin master
Step 8: Build you doc on Read the docs¶
You can create an account on Read the docs to build your documentation hosted on GitLab.