Merge pull request #120 from alan-turing-institute/setup-jupyterbook

Setup JupyterBook

.gitignore

@@ -5,6 +5,7 @@ dist/
 
 # Ignore Sphinx build artifacts
 docs/build/
+docs/_build/
 docs/generated/
 .sphinx-build-environment
 

README.md

@@ -59,6 +59,14 @@ best_emulator = ae.load_model("best_model")
 best_emulator.predict(X)
 ```
 
+## documentation
+
+The documentation is currently created using JupyterBook. To build the documentation locally, run:
+
+```bash
+poetry run jupyter-book build docs
+```
+
 ## Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

docs/_config.yml

@@ -0,0 +1,63 @@
+title: "AutoEmulate: An emulator platform for Digital Twins"
+author: Martin Stoffel
+# logo: logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: autoemulate-docs.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+only_build_toc_files: true
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/alan-turing-institute/autoemulate
+  path_to_book: docs
+  branch: main
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+sphinx:
+  extra_extensions:
+    - 'sphinx.ext.autodoc'
+    - 'sphinx.ext.napoleon'
+    - 'sphinx.ext.viewcode'
+  config:
+    add_module_names: False
+    autodoc_typehints: none
+    autoclass_content: class
+    bibtex_reference_style: author_year
+    intersphinx_mapping:
+      python:
+        - https://docs.python.org/3
+        - null
+      pandas:
+        - http://pandas.pydata.org/pandas-docs/stable/
+        - null
+      # tensorflow:
+      #  - http://www.tensorflow.org/api_docs/python
+      #  - https://raw.githubusercontent.com/GPflow/tensorflow-intersphinx/master/tf2_py_objects.inv
+      numpy:
+        - https://numpy.org/doc/stable/
+        - null
+      matplotlib:
+        - http://matplotlib.org/stable/
+        - null
+      sklearn:
+        - http://scikit-learn.org/stable
+        - null
+    language: en
+    copybutton_prompt_text: "$"

docs/_toc.yml

@@ -0,0 +1,43 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: index
+chapters:
+
+- file: getting-started/index
+  sections:
+  # - file: getting-started/overview
+  # - file: getting-started/data_requirements
+  - file: getting-started/installation
+  - file: getting-started/quickstart
+
+- file: reference/index
+  sections:
+  - file: reference/compare
+  - file: reference/cv
+  - file: reference/datasets
+  - file: reference/experimental_design
+  - file: reference/hyperparam_searching
+  - file: reference/logging_config
+  - file: reference/metrics
+  - file: reference/model_processing
+  - file: reference/plotting
+  - file: reference/printing
+  - file: reference/save
+  - file: reference/utils
+  - file: reference/demos/index
+    sections:
+    - file: reference/demos/projectile
+  - file: reference/emulators/index
+    sections:
+    - file: reference/emulators/gaussian_process_sk
+    - file: reference/emulators/gaussian_process
+    - file: reference/emulators/gradient_boosting
+    - file: reference/emulators/neural_net_sk
+    - file: reference/emulators/neural_net_torch
+    - file: reference/emulators/polynomials
+    - file: reference/emulators/random_forest
+    - file: reference/emulators/rbf
+    - file: reference/emulators/support_vector_machines
+    - file: reference/emulators/xgboost

docs/getting-started/best_model_meta.json

@@ -0,0 +1 @@
+{"model": "GaussianProcessSk", "scikit-learn": "1.4.0", "numpy": "1.23.5"}

docs/getting-started/index.md

@@ -0,0 +1,4 @@
+# Getting started
+
+In this part of the documentation, we will show you how to get started with `AutoEmulate`.
+We will show you how to install `AutoEmulate` and how to extend it. We will also provide you with some tutorials to get you started with `AutoEmulate`.

docs/getting-started/installation.md

@@ -0,0 +1,39 @@
+# Installation instructions
+
+AutoEmulate is a Python package that can be installed in a number of ways. In this section we will describe the main ways to install the package.
+
+## Install from PyPI
+
+This is the easiest way to install AutoEmulate.
+
+Currently, because we are in active development, you have to install the development version from GitHub:
+
+```bash
+$ pip install git+https://github.com/alan-turing-institute/autoemulate.git
+```
+
+## Install using Poetry
+
+If you are a code contributor, you can also use [Poetry](https://python-poetry.org/)
+
+```bash
+$ git clone https://github.com/alan-turing-institute/autoemulate.git
+```
+
+Navigate into the directory:
+
+```
+$ cd autoemulate
+```
+
+Set up poetry:
+
+```
+$ poetry install
+```
+
+Enter the poetry shell:
+
+```
+$ poetry shell
+```