This project is intended to demonstrate the standard python project work-flow that is being followed at Computational Mechanics lab. By presenting the basic folder structure, this project focuses of documentation of the project and source code. These documentations makes a coding packages easy accessible and collaborative. Sphinx documentation tool is used to generate web version of the project.
To demonstrate the entire workflow, this projects considered simple maths.py file containing two classes that stores two numbers and performs addition, subtraction, multiplication, and division operations on them. The presented python code is containing properly formatted docstrings, which are mandatory for better documentations.
Before starting, look a few open source projects documentation that generated using Sphinx and familiarize yourself with what we are going to finally make.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
To follow along with the examples, you need to install below packages into your system.
Note: If have installed updated versions of below packages, please ignore the following steps.
After downloading the Anaconda, follow Anaconda Install instruction based on your system configuration.
Important: While installing the anaconda, make sure below boxes are checked.
Open command prompt as administrator and use below command to install sphinx in your machine.
pip install -U sphinx
Note: If you are not able to execute above command through command prompt, open anaconda prompt as administrator to execute the commands.
sphinx-build --version
Use this command to check sphinx version.
Sphinx offers flexibility in changing the webpage format. read_docs is the most popular theme. In order to install it use this command
pip install sphinx_rtd_theme
So far, we installed all the required modules that necessary to develop documentation. Please refer to _doc/README.md for documentation process using Sphinx.
.
├── _data
├── _demo
├── _doc
├── _docker
├── _flats
├── _src
├── _scripts
├── _test
└── setup.py
An overview of what each of these does:
File/Directory | Description |
---|---|
_data |
This directory contains the data that will be used for test scripts. These will be mesh files created in gmsh |
_demo |
This directory will contain the demos supplied with the package |
_doc |
This directory will contain the documentation for the package. This will be automatically generated from python files |
_docker |
This directory will contain the DockerFile to build the docker image for this project |
_flats |
This directory will contain the flat programs based on which modules will be developed |
_src |
`This is the main directory for the source code of the package |
_scripts |
This directory will contain scripts to generate documentation |
_test |
This directory will contain the unit tests |
setup.py |
This file will help to install the package with pip |