New Project Setup

How to start a new project in PyCharm and set it up with Poetry, Sphinx and Test folders. This tutorial will show you how to start your project as you mean to go on, making it easy to maintain good development practise.

1. poetry and code setup

We start by opening a terminal and navigating to where we want to store our project:

cd <new project directory>

Then we create our new poetry project:

poetry new Example

This will set up the file structure with a Python package example and tests both with the appropriate __init__.py and add a README.md and pyproject.toml

2. New git Project in Pycharm

To open your project in PyCharm:

File -> Open

We will then need to set up the project interpreter. To do this go to:

File -> Settings -> Project:Example -> Project interpreter

Select your interpreter, this is what PyCharm will use to run any code and provide a python console.

It will give the option of any version of python you have installed and you can add more versions as needed.

Click OK to close

We now want to make this a git repository before we make any changes so if we make mistakes during set up we can roll them back. In this case we are going to create a repository on GitHub so that we also have an external backup.

VCS -> Share project on GitHub

You'll need to name your repository (probably stick to the same name as the project) and provide a description.

After you'll need to run an initial commit and push to populate the git repository. I would commit everything at this stage.

At this point we have a blank project with a name, description (on the git repository) and no content. Let's set up to start developing a python package.

README.md

Since we already have a lot of the basic information needed for it you should think about writting an initial README.md.

You already have a name for the project and a description. We also have version (initial so something like: 0.0.1) and our own details for authorship information.

3. Sphinx Setup

We're all set up for our coding environment but what about documentation? We want that set up as early as possible too so we can document as we go.

Add a docs directory to the project.

This folder is where we will sort all our documentation files and builds. Using Sphinx we will set up this folder to make updating and hosting our docs as easy as possible.

First lets set up Sphinx in the docs folder:

cd docs

sphinx-quickstart

This will start the sphinx quickstart utility which will set up you documentation for you based on some simple questions.

> Separate source and build directories (y/n) [n]: y

We want to have the source files for our documentation stored seperately in the docs folder to our build files just to keep everything tidier.

> Name prefix for templates and static dir [_]:

We can leave this with the default prefix unless you particularly want to change it. The directories are used for HTML templates and custom stylesheets.

> Project name: Example

> Author name(s): Penn Rainford

> Project release []: 0.0.1

This is where we pass Sphinx the basic information for our system. This should match the information included in the README.md.

If your not writing your documentation in English you'll need to set the language based on the guidance given, but otherwise, go with the default.

>Project language [en]:

We recommend writing docs in reStructuredText but if you want to write it in plain text you can but should indicate so here. reStructuredText has a lot of great options and features though that work well with Sphinx so is the default.

> Source file suffix [.rst]:

We have the option to call our master document or homepage something other than index but this is a good default.

> Name of your master document (without suffix) [index]:

We then work through a set of extensions we may want to add to our Sphinx setup.

autodoc - generates api documentation from docstrings (recommend: yes)
doctest - tests code snippets in doctest blocks (recommend: no)
intersphinx - links sphinx documentation between projects (recommend: no)
todo - lets us write todos into the documentation without them being in the built documentation (recommend: yes)
coverage - checks that the documentation covers the whole of the code (recommend: yes)
ingmath - renders maths into images (recommend: yes)
Mathjax - allows maths to be rendered by mathjax in browser (recommend: no)
ifconfig - allows us to use if statements in our documentation for the inclusion of content. (recommend: no)
viewcode - adds a link to view source code from the api style documentation (recommend: yes)
githubpages - adds a .nojekyll file to the build code for use with github pages (recommend: yes)

Some of these we recommend no just because they're not needed in general but they can add great features to your documentation so do look into them if you are interested.

Finally there are two options to create scripts that will make building your documentation easy. It is recommended that you generate both these files so that the documentation process is as easy as possible.

> Create Makefile? (y/n) [y]: y

> Create Windows command file? (y/n) [y]: y

This will finish the Sphinx quick start process but for a couple of things we have a little more setup.

To allow this Sphinx set up to be used easily with GitHub Pages we need to make some changes.

First we copy the .nojekyll file to the docs directory, this is where GitHub Pages will look for it.

Second we add a index redirect to the docs directory to point GitHub Pages to the correct index in the build/html subdirectory. To do this we add an index.html file to docs with a single line of code:

Note that you will need to fill in your own github USERNAME and PROJECTNAME to direct it to the correct projects docs directory.

To allow Sphinx to find our DocStrings easily in our code we add to the config file:

import os

import sys

sys.path.insert(0, os.path.abspath('.'))

sys.path.insert(0, '/home/PycharmProjects/Example')

The first three lines will already be in the config file they just need to be uncommented. The last line will make sure that Sphinx looks for code in your python package. This will work best if you make good use of adding objects and modules to the __init__.py files in your python package.

Updating and Maintenance

This set up is a great starting point for a project and will help you to remember to document and test as you go. There are a few additional tasks that should be remembered.

Commit and push this to GitHub when you finish and regularly to keep it up to date
In GitHub set up your Pages
Add requirements using Poetry so they are properly tracked and installed
Use make html to build documentation regularly to keep it upto date.
Keep your README.md upto date with description and install instructions.

Page updated

Report abuse