Musical Instruments Corrosion Data documentation

This is the documentation for the website for Musical Instruments Corrosion Data.

The code consists of the main.py script which serves all the websites routes and utilizes the various libraries, both included and sourced elsewhere.

The main requirements are:

  • Python 3.12 or newer

  • Python virtual environment with the corrosion data code

  • pip (to install packages in the venv)

  • Bottle 0.13.2 (or possibly newer) - to serve the site

  • openpyxl 3.1.5 (or possibly newer) - for reading/writing excel-files

  • plotly 5.24.1 (or possibly newer) - for creating graphs

  • sphinx - for auto-rendering the documentation

  • sphinx_rtd_theme - theme for sphinx

In the virtual environment, you can start the bottle-server with:

python3 main.py

Installation

To install the corrosion website, you have to do these main steps:

  1. Create the python virtual environment (venv)

  2. Copy the source files to the venv

  3. Install the required packages in the venv using pip

Please see below for detailed instructions on how to do these steps.

Create The Virtual Environment

This is a short guide to creating the python virtual environment (venv), which in this case has already been done, so it does not need to be done. But in just in case, here’s how.

  1. Go to the folder where you intend to create the venv under. We recommend that you create a top folder, where the venv will become its sub-folder.

  2. While standing in that created folder, write:

python3 -m venv corrosion

  1. Hit enter and the corrosion-venv will be created in the “corrosion”-folder.

In order to use the environment you have to use the shell source command in conjunction with the activate script that resides in the venv you just created:

source corrosion/bin/activate

Then you can proceed to install packages and other things needed in the venv.

Install Packages

This is how to install packages in the venv that you created.

First activate the venv for use:

source corrosion/bin/activate
cd corrosion

Then proceed to install packages:

pip install bottle
pip install openpyxl
pip install plotly
pip install sphinx sphinx_rtd_theme

Then head to a web-browser at localhost:8080

How To Setup Sphinx For Documentation Rendering

After having installed the necessary packages, including sphinx, you can proceed to setup the documentation rendering. This has already been done, so this is here primarily for instructional purposes.

First, create the docs folder:

mkdir docs
cd docs

Then create the sphinx folder:

sphinx-quickstart

Answer just the defaults on all questions from the script.

In the docs-folder should now resides several files. Edit the conf.py file and add the following to its top:

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

Set the extensions-parameter of the conf.py file to the following:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon'
]

Change the html_theme parameter to:

html_theme = 'sphinx_rtd_theme'

Save the conf.py file and exit it.

Then go to the corrosion folder and write:

sphinx-apidoc -o docs *

And it will generate .rst files for your code in the docs-folder. This must be repeated for any new modules that are added.

In order to render the html of the documentation at any point, run:

make html

Then the new html code should be available in the docs-folder under “_build/html/index.html”.

How To Install On Apache Web-Server

corrosion