Skip to content

Commit

Permalink
Add basic website structure (#114)
Browse files Browse the repository at this point in the history
* Add basic website structure

* Exclude built docs

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
  • Loading branch information
adamltyson and pre-commit-ci[bot] authored Oct 16, 2024
1 parent 10f0fa3 commit 67c8fb1
Show file tree
Hide file tree
Showing 9 changed files with 289 additions and 0 deletions.
42 changes: 42 additions & 0 deletions .github/workflows/docs_build_and_deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
name: Build Sphinx docs and deploy to GitHub Pages

# Generate the documentation on all merges to main, all pull requests, or by
# manual workflow dispatch. The build job can be used as a CI check that the
# docs still build successfully. The deploy job only runs when a tag is
# pushed and actually moves the generated html to the gh-pages branch
# (which triggers a GitHub pages deployment).
on:
push:
branches:
- main
tags:
- '*'
pull_request:
workflow_dispatch:


jobs:
linting:
# scheduled workflows should not run on forks
if: (${{ github.event_name == 'schedule' }} && ${{ github.repository_owner == 'SainsburyWellcomeCentre' }} && ${{ github.ref == 'refs/heads/main' }}) || (${{ github.event_name != 'schedule' }})
runs-on: ubuntu-latest
steps:
- uses: neuroinformatics-unit/actions/lint@v2

build_sphinx_docs:
name: Build Sphinx Docs
runs-on: ubuntu-latest
steps:
- uses: neuroinformatics-unit/actions/build_sphinx_docs@v2

deploy_sphinx_docs:
name: Deploy Sphinx Docs
needs: build_sphinx_docs
permissions:
contents: write
if: github.event_name == 'push' && github.ref_type == 'tag'
runs-on: ubuntu-latest
steps:
- uses: neuroinformatics-unit/actions/deploy_sphinx_docs@v2
with:
secret_input: ${{ secrets.GITHUB_TOKEN }}
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -62,3 +62,6 @@ coverage.xml

# PyPI distribution / packages
dist/

# Sphinx documentation
docs/build/
2 changes: 2 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,5 @@ recursive-include images *
recursive-include documents *.cff
recursive-include documents *.md
recursive-include neuralplayground *.md

recursive-exclude docs *
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
35 changes: 35 additions & 0 deletions docs/make.bat
Original file line number Diff line number Diff line change
@@ -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

%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.https://www.sphinx-doc.org/
exit /b 1
)

if "%1" == "" goto help

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

:end
popd
8 changes: 8 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
linkify-it-py
myst-parser
nbsphinx
pydata-sphinx-theme
setuptools-scm
sphinx
sphinx-autodoc-typehints
sphinx-sitemap
122 changes: 122 additions & 0 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

import os
import sys

import setuptools_scm

# Used when building API docs, put the dependencies
# of any class you are documenting here
autodoc_mock_imports = []

# Add the module path to sys.path here.
# If the directory is relative to the documentation root,
# use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath("../.."))

project = "NeuralPlayground"
copyright = "2024, University College London"
author = "University College London"
try:
release = setuptools_scm.get_version(root="../..", relative_to=__file__)
except LookupError:
# if git is not initialised, still allow local build
# with a dummy version
release = "0.0.0"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
"sphinx.ext.napoleon",
"sphinx.ext.autodoc",
"sphinx.ext.githubpages",
"sphinx_autodoc_typehints",
"sphinx.ext.autosummary",
"sphinx.ext.viewcode",
"sphinx.ext.intersphinx",
"sphinx_sitemap",
"myst_parser",
"nbsphinx",
]

# Configure the myst parser to enable cool markdown features
# See https://sphinx-design.readthedocs.io
myst_enable_extensions = [
"amsmath",
"colon_fence",
"deflist",
"dollarmath",
"fieldlist",
"html_admonition",
"html_image",
"linkify",
"replacements",
"smartquotes",
"strikethrough",
"substitution",
"tasklist",
]
# Automatically add anchors to markdown headings
myst_heading_anchors = 3

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# Automatically generate stub pages for API
autosummary_generate = True
autodoc_default_flags = ["members", "inherited-members"]

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
"**.ipynb_checkpoints",
# to ensure that include files (partial pages) aren't built, exclude them
# https://github.com/sphinx-doc/sphinx/issues/1965#issuecomment-124732907
"**/includes/**",
]

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "pydata_sphinx_theme"
html_title = "NeuralPlayground"

# Customize the theme
html_theme_options = {
"icon_links": [
{
# Label for this link
"name": "GitHub",
# URL where the link will redirect
"url": "https://github.com/SainsburyWellcomeCentre/NeuralPlayground", # required
# Icon class (if "type": "fontawesome"),
# or path to local image (if "type": "local")
"icon": "fa-brands fa-github",
# The type of image to be used (see below for details)
"type": "fontawesome",
}
],
"logo": {
"text": f"{project} v{release}",
},
}

# Redirect the webpage to another URL
# Sphinx will create the appropriate CNAME file in the build directory
# The default is the URL of the GitHub pages
# https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html
github_user = "SainsburyWellcomeCentre"
html_baseurl = f"https://{github_user}.github.io/{project}"
sitemap_url_scheme = "{link}"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
11 changes: 11 additions & 0 deletions docs/source/getting_started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Getting started

Here you may demonstrate the basic functionalities your package.

You can include code snippets using the usual Markdown syntax:

```python
from my_package import my_function

result = my_function()
```
46 changes: 46 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
.. NeuralPlayground documentation master file, created by
sphinx-quickstart on Fri Dec 9 14:12:42 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to NeuralPlayground's documentation!
=========================================================

.. toctree::
:maxdepth: 2
:caption: Contents:

getting_started
api_index

By default the documentation includes the following sections:

* Getting started. Here you could describe the basic functionalities of your package. To modify this page, edit the file ``docs/source/getting_started.md``.
* API: here you can find the auto-generated documentation of your package, which is based on the docstrings in your code. To modify which modules/classes/functions are included in the API documentation, edit the file ``docs/source/api_index.rst``.

You can create additional sections with narrative documentation,
by adding new ``.md`` or ``.rst`` files to the ``docs/source`` folder.
These files should start with a level-1 (H1) header,
which will be used as the section title. Sub-sections can be created
with lower-level headers (H2, H3, etc.) within the same file.

To include a section in the rendered documentation,
add it to the ``toctree`` directive in this (``docs/source/index.rst``) file.

For example, you could create a ``docs/source/installation.md`` file
and add it to the ``toctree`` like this:

.. code-block:: rst
.. toctree::
:maxdepth: 2
:caption: Contents:
getting_started
installation
api_index
Index & Search
--------------
* :ref:`genindex`
* :ref:`search`

0 comments on commit 67c8fb1

Please sign in to comment.