[DOCUMENTATION] Initial ReadTheDocs

.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: "2"
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.10"
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+sphinx:
+  configuration: docs/source/conf.py

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Steven Atkinson
+Copyright (c) 2024 Steven Atkinson
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,146 +4,4 @@ This repository handles training, reamping, and exporting the weights of a model
 For playing trained models in real time in a standalone application or plugin, see the partner repo,
 [NeuralAmpModelerPlugin](https://github.com/sdatkinson/NeuralAmpModelerPlugin).
 
-* [How to use](https://github.com/sdatkinson/neural-amp-modeler/tree/main#how-to-use)
-  * [Google Colab](https://github.com/sdatkinson/neural-amp-modeler/tree/main#google-colab)
-  * [GUI](https://github.com/sdatkinson/neural-amp-modeler/tree/main#gui)
-  * [The command line trainer (all features)](https://github.com/sdatkinson/neural-amp-modeler/tree/main#the-command-line-trainer-all-features)
-* [Standardized reamping files](https://github.com/sdatkinson/neural-amp-modeler/tree/main#standardized-reamping-files)
-* [Other utilities](https://github.com/sdatkinson/neural-amp-modeler/tree/main#other-utilities)
-
-## How to use
-There are three main ways to use the NAM trainer. There are two simplified trainers available (1) in your browser via Google Colab and (2) Locally via a GUI. There is also a full-featured trainer for power users than can be run from the command line.
-
-### Google Colab
-
-If you don't have a good computer for training ML models, you use Google Colab to train
-in the cloud using the pre-made notebooks under `bin\train`.
-
-For the very easiest experience, open 
-[`easy_colab.ipynb` on Google Colab](https://colab.research.google.com/github/sdatkinson/neural-amp-modeler/blob/27c6a048025e7894e0d89579cfda6c59d93e0f20/bin/train/easy_colab.ipynb) 
-and follow the steps!
-
-### GUI
-
-After installing the Python package, a GUI can be accessed by running `nam` in the command line.
-
-### The command line trainer (all features)
-
-Alternatively, you can clone this repo to your computer and use it locally.
-
-#### Installation
-
-Installation uses [Anaconda](https://www.anaconda.com/) for package management.
-
-For computers with a CUDA-capable GPU (recommended):
-
-```bash
-conda env create -f environment_gpu.yml
-```
-_Note: you may need to modify the CUDA version if your GPU is older. Have a look at [nVIDIA's documentation](https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#cuda-major-component-versions__table-cuda-toolkit-driver-versions) if you're not sure._
-
-Otherwise, for a CPU-only install (will train much more slowly):
-
-```bash
-conda env create -f environment_cpu.yml
-```
-
-_Note: if Anaconda takes a long time "`Solving environment...`", then you can speed up installing the environment by using the mamba experimental sovler with `--experimental-solver=libmamba`._
-
-Then activate the environment you've created with
-
-```bash
-conda activate nam
-```
-
-#### Train models (GUI)
-After installing, you can open a GUI trainer by running
-
-```bash
-nam
-```
-
-from the terminal.
-
-#### Train models (Python script)
-For users looking to get more fine-grained control over the modeling process, 
-NAM includes a training script that can be run from the terminal. In order to run it
-#### Download audio files
-Download the [v1_1_1.wav](https://drive.google.com/file/d/1CMj2uv_x8GIs-3X1reo7squHOVfkOa6s/view?usp=drive_link) and [output.wav](https://drive.google.com/file/d/1e0pDzsWgtqBU87NGqa-4FbriDCkccg3q/view?usp=drive_link) to a folder of your choice 
-
-##### Update data configuration 
-Edit `bin/train/data/single_pair.json` to point to relevant audio files: 
-```json
-    "common": {
-        "x_path": "C:\\path\\to\\v1_1_1.wav",
-        "y_path": "C:\\path\\to\\output.wav",
-        "delay": 0
-    }
-```
-
-##### Run training script
-Open up a terminal. Activate your nam environment and call the training with
-```bash
-python bin/train/main.py \
-bin/train/inputs/data/single_pair.json \
-bin/train/inputs/models/demonet.json \
-bin/train/inputs/learning/demo.json \
-bin/train/outputs/MyAmp
-```
-
-`data/single_pair.json` contains the information about the data you're training
-on   
-`models/demonet.json` contains information about the model architecture that
-is being trained. The example used here uses a `feather` configured `wavenet`.  
-`learning/demo.json` contains information about the training run itself (e.g. number of epochs).
-
-The configuration above runs a short (demo) training. For a real training you may prefer to run something like,
-
-```bash
-python bin/train/main.py \
-bin/train/inputs/data/single_pair.json \
-bin/train/inputs/models/wavenet.json \
-bin/train/inputs/learning/default.json \
-bin/train/outputs/MyAmp
-```
-
-As a side note, NAM uses [PyTorch Lightning](https://lightning.ai/pages/open-source/) 
-under the hood as a modeling framework, and you can control many of the Pytorch Lightning configuration options from `bin/train/inputs/learning/default.json`
-
-#### Export a model (to use with [the plugin](https://github.com/sdatkinson/NeuralAmpModelerPlugin))
-Exporting the trained model to a `.nam` file for use with the plugin can be done
-with:
-
-```bash
-python bin/export.py \
-path/to/config_model.json \
-path/to/checkpoints/epoch=123_val_loss=0.000010.ckpt \
-path/to/exported_models/MyAmp
-```
-
-Then, point the plugin at the exported `model.nam` file and you're good to go!
-
-## Standardized reamping files
-
-NAM can train using any paired audio files, but the simplified trainers (Colab and GUI) can use some pre-made audio files for you to reamp through your gear.
-
-You can use any of the following files:
-
-* [v3_0_0.wav](https://drive.google.com/file/d/1Pgf8PdE0rKB1TD4TRPKbpNo1ByR3IOm9/view?usp=drive_link) (preferred)
-* [v2_0_0.wav](https://drive.google.com/file/d/1xnyJP_IZ7NuyDSTJfn-Jmc5lw0IE7nfu/view?usp=drive_link)
-* [v1_1_1.wav](https://drive.google.com/file/d/1CMj2uv_x8GIs-3X1reo7squHOVfkOa6s/view?usp=drive_link)
-* [v1.wav](https://drive.google.com/file/d/1jxwTHOCx3Zf03DggAsuDTcVqsgokNyhm/view?usp=drive_link)
-
-## Other utilities
-
-#### Run a model on an input signal ("reamping")
-
-Handy if you want to just check it out without needing to use the plugin:
-
-```bash
-python bin/run.py \
-path/to/source.wav \
-path/to/config_model.json \
-path/to/checkpoints/epoch=123_val_loss=0.000010.ckpt \
-path/to/output.wav
-```
+For documentation, check out the [ReadTheDocs](https://neural-amp-modeler.readthedocs.io).

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
+.

docs/source/.gitignore

@@ -0,0 +1,3 @@
+_build/
+generated/
+html/

docs/source/api.rst

@@ -0,0 +1,10 @@
+API
+===
+
+.. autosummary::
+   :toctree: generated
+
+   nam.data
+   nam.models
+   nam.train
+   nam.util

docs/source/conf.py

@@ -0,0 +1,40 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# Build locally
+# (e.g. https://readthedocs.org/projects/neural-amp-modeler/builds/23551748/)
+#
+# $ python -m sphinx -T -b html -d _build/doctrees -D language=en . ./html
+
+# -- Project information
+
+project = "neural-amp-modeler"
+copyright = "2024 Steven Atkinson"
+author = "Steven Atkinson"
+
+release = "0.8"
+version = "0.8.1"
+
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+templates_path = ["_templates"]
+
+# -- Options for HTML output
+
+html_theme = "sphinx_rtd_theme"
+
+# -- Options for EPUB output
+epub_show_urls = "footnote"

docs/source/index.rst

@@ -0,0 +1,17 @@
+Welcome to ``neural-amp-modeler``'s documentation!
+==================================================
+
+``neural-amp-modeler`` is a Python package for creating neural network models of
+your guitar (bass, etc) gear. It works by using two audio files--an input "DI"
+file as well as an output "reamp" file, showing how the gear responds to
+different incoming signals.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   tutorials/main
+   api

docs/source/installation.rst

@@ -0,0 +1,18 @@
+Local Installation
+==================
+
+It's recommended to use Anaconda to manage your install. Get Anaconda from
+https://www.anaconda.com/download
+
+If your computer has an nVIDIA GPU, you should install a GPU-compatible version 
+of PyTorch first:
+
+.. code-block:: console
+
+   $ conda install -y pytorch pytorch-cuda=11.8 -c pytorch -c nvidia
+
+Next, install NAM using pip:
+
+.. code-block:: console
+
+   $ pip install neural-amp-modeler