From f1bcc4dbff50a684ba714394bc11e1b045bdd4c4 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 09:30:55 +0200 Subject: [PATCH 1/8] Moved tutorials --- docs/source/index.rst | 19 ------------------- ...torial_01.ipynb => example_tutorial.ipynb} | 0 2 files changed, 19 deletions(-) delete mode 100644 docs/source/index.rst rename tutorials/{tutorial_01.ipynb => example_tutorial.ipynb} (100%) diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index df6c5b3..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. Documentation master file, created by - sphinx-quickstart on Sun Jun 22 11:14:00 2025. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -python-template documentation -============================= - -Add your content using ``reStructuredText`` syntax. See the -`reStructuredText `_ -documentation for details. - - -.. toctree:: - :maxdepth: 2 - :caption: Tutorials: - :glob: - - tutorials/* \ No newline at end of file diff --git a/tutorials/tutorial_01.ipynb b/tutorials/example_tutorial.ipynb similarity index 100% rename from tutorials/tutorial_01.ipynb rename to tutorials/example_tutorial.ipynb From df05e505c50ebb8c0d576dfd81fd5aaa3d77b49f Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 09:31:49 +0200 Subject: [PATCH 2/8] Updated conf and wrote docs in markdown --- docs/source/api.md | 6 ++ docs/source/conf.py | 98 ++++++++++++++++++++++++- docs/source/index.md | 11 +++ docs/source/quickstart.md | 42 +++++++++++ docs/source/tutorials.md | 8 ++ docs/source/tutorials/tutorial_01.ipynb | 51 ------------- 6 files changed, 163 insertions(+), 53 deletions(-) create mode 100644 docs/source/api.md create mode 100644 docs/source/index.md create mode 100644 docs/source/quickstart.md create mode 100644 docs/source/tutorials.md delete mode 100644 docs/source/tutorials/tutorial_01.ipynb diff --git a/docs/source/api.md b/docs/source/api.md new file mode 100644 index 0000000..a1c08b6 --- /dev/null +++ b/docs/source/api.md @@ -0,0 +1,6 @@ +# API + +Description of the API + +```{toctree} +:maxdepth: 1 \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 9c91e46..d7af860 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -5,7 +5,8 @@ import os import shutil - +# At the top. +import sphinx_bootstrap_theme def copy_tutorials(app): src = os.path.abspath("../tutorials") @@ -36,14 +37,107 @@ def setup(app): "nbsphinx", "sphinx.ext.mathjax", "sphinx.ext.autodoc", + "myst_parser", # enable Markdown support ] templates_path = ["_templates"] exclude_patterns = [] +# Recognize both .rst and .md +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "sphinx_rtd_theme" +# html_theme = "furo" +# conf.py +# ... + +# Activate the theme. +html_theme = 'bootstrap' +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() + +# (Optional) Logo. Should be small enough to fit the navbar (ideally 24x24). +# Path should be relative to the ``_static`` files directory. +# html_logo = "my_logo.png" + +# Theme options are theme-specific and customize the look and feel of a +# theme further. +html_theme_options = { + # Navigation bar title. (Default: ``project`` value) + 'navbar_title': "python-template", + + # Tab name for entire site. (Default: "Site") + + 'navbar_site_name': "Site", + + # A list of tuples containing pages or urls to link to. + # Valid tuples should be in the following forms: + # (name, page) # a link to a page + # (name, "/aa/bb", 1) # a link to an arbitrary relative url + # (name, "http://example.com", True) # arbitrary absolute url + # Note the "1" or "True" value above as the third argument to indicate + # an arbitrary url. + 'navbar_links': [ + ("Quickstart", "quickstart"), + ("Tutorials", "tutorial"), + ("API", "api"), + # ("Link", "http://example.com", True), + ], + + # Render the next and previous page links in navbar. (Default: true) + 'navbar_sidebarrel': False, + + # Render the current pages TOC in the navbar. (Default: true) + 'navbar_pagenav': False, + + # Tab name for the current pages TOC. (Default: "Page") + 'navbar_pagenav_name': "Page", + + # Global TOC depth for "site" navbar tab. (Default: 1) + # Switching to -1 shows all levels. + 'globaltoc_depth': 2, + + # Include hidden TOCs in Site navbar? + # + # Note: If this is "false", you cannot have mixed ``:hidden:`` and + # non-hidden ``toctree`` directives in the same page, or else the build + # will break. + # + # Values: "true" (default) or "false" + 'globaltoc_includehidden': "true", + + # HTML navbar class (Default: "navbar") to attach to
element. + # For black navbar, do "navbar navbar-inverse" + 'navbar_class': "navbar navbar-inverse", + + # Fix navigation bar to top of page? + # Values: "true" (default) or "false" + 'navbar_fixed_top': "true", + + # Location of link to source. + # Options are "nav" (default), "footer" or anything else to exclude. + 'source_link_position': "footer", + + # Bootswatch (http://bootswatch.com/) theme. + # + # Options are nothing (default) or the name of a valid theme + # such as "cosmo" or "sandstone". + # + # The set of valid themes depend on the version of Bootstrap + # that's used (the next config option). + # + # Currently, the supported themes are: + # - Bootstrap 2: https://bootswatch.com/2 + # - Bootstrap 3: https://bootswatch.com/3 + 'bootswatch_theme': "united", + + # Choose Bootstrap version. + # Values: "3" (default) or "2" (in quotes) + 'bootstrap_version': "3", +} + html_static_path = ["_static"] diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000..d082474 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,11 @@ +# Welcome + +Write the documentation of your python package here + +```{toctree} +:maxdepth: 2 +:caption: Contents + +quickstart.md +tutorials.md +api.md diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md new file mode 100644 index 0000000..cc6dd8c --- /dev/null +++ b/docs/source/quickstart.md @@ -0,0 +1,42 @@ +# Quickstart + +Clone the repo + +``` +git clone ... +``` + +Create and activate python environment + +``` +python -m venv env +source env/bin/activate +pip install --upgrade pip +``` + +Install the code and requirements with pip + +``` +pip install -e . +``` + +Run the code with + +``` +template-python +``` + +# Build docs + +``` +# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 +sphinx-apidoc -o docs/ src/app/ +cd docs/ +make clean +make html +cd ../ +open docs/_build/html/index.html +``` + +```{toctree} +:maxdepth: 1 \ No newline at end of file diff --git a/docs/source/tutorials.md b/docs/source/tutorials.md new file mode 100644 index 0000000..8e9b07e --- /dev/null +++ b/docs/source/tutorials.md @@ -0,0 +1,8 @@ +# Tutorials + +```{toctree} +:maxdepth: 1 +:caption: Tutorials +:glob: + +tutorials/* \ No newline at end of file diff --git a/docs/source/tutorials/tutorial_01.ipynb b/docs/source/tutorials/tutorial_01.ipynb deleted file mode 100644 index 4f568bb..0000000 --- a/docs/source/tutorials/tutorial_01.ipynb +++ /dev/null @@ -1,51 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "efb79425-958b-412c-afa9-055e27a69baa", - "metadata": {}, - "source": [ - "# Tutorial 1" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "68ad1562-4953-444c-96c7-9026bcc54cc7", - "metadata": {}, - "outputs": [ - { - "name": "stdout", - "output_type": "stream", - "text": [ - "Example tutorial which will be published in the docs!\n" - ] - } - ], - "source": [ - "print(\"Example tutorial which will be published in the docs!\")" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.13.3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} From 143251afe569e149df3982c6033f78ce1443b0b2 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 09:32:26 +0200 Subject: [PATCH 3/8] Updated gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 99ffb91..eaf73dd 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/source/tutorials/ # PyBuilder .pybuilder/ From 55449c7a684078941e2706e856b3b42d86b75fd5 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 09:33:05 +0200 Subject: [PATCH 4/8] Updated instructions --- README.md | 4 ---- docs/source/quickstart.md | 4 ---- 2 files changed, 8 deletions(-) diff --git a/README.md b/README.md index 92c44e9..8ca65e2 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,6 @@ template-python ``` -# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 -sphinx-apidoc -o docs/ src/app/ -cd docs/ -make clean make html cd ../ open docs/_build/html/index.html diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md index cc6dd8c..a2d6ec8 100644 --- a/docs/source/quickstart.md +++ b/docs/source/quickstart.md @@ -29,10 +29,6 @@ template-python # Build docs ``` -# https://medium.com/@pratikdomadiya123/build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594 -sphinx-apidoc -o docs/ src/app/ -cd docs/ -make clean make html cd ../ open docs/_build/html/index.html From 075bcc894e7960e3cc8e751feddcdf1127cc822d Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 09:34:17 +0200 Subject: [PATCH 5/8] Removed sidebar --- docs/source/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index d7af860..02476b2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -141,3 +141,7 @@ def setup(app): } html_static_path = ["_static"] + +html_sidebars = { + '**': [] +} \ No newline at end of file From 1d7308470182a6cfb69f3a775b0a9b4462dee71a Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 09:52:12 +0200 Subject: [PATCH 6/8] Updated navbar color --- docs/source/conf.py | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 02476b2..4b57f55 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,14 +21,16 @@ def copy_tutorials(app): def setup(app): app.connect("builder-inited", copy_tutorials) + # app.add_stylesheet("my-styles.css") + app.add_css_file("custom.css") # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = "python-template" -copyright = "2025, Max Lindqvist" -author = "Max Lindqvist" +copyright = "2025, Max" +author = "Max" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -40,7 +42,6 @@ def setup(app): "myst_parser", # enable Markdown support ] -templates_path = ["_templates"] exclude_patterns = [] # Recognize both .rst and .md @@ -112,7 +113,7 @@ def setup(app): # HTML navbar class (Default: "navbar") to attach to
element. # For black navbar, do "navbar navbar-inverse" - 'navbar_class': "navbar navbar-inverse", + 'navbar_class': "navbar inverse", # Fix navigation bar to top of page? # Values: "true" (default) or "false" @@ -133,7 +134,7 @@ def setup(app): # Currently, the supported themes are: # - Bootstrap 2: https://bootswatch.com/2 # - Bootstrap 3: https://bootswatch.com/3 - 'bootswatch_theme': "united", + 'bootswatch_theme': "flatly", # Choose Bootstrap version. # Values: "3" (default) or "2" (in quotes) @@ -141,7 +142,9 @@ def setup(app): } html_static_path = ["_static"] +templates_path = ['_templates'] + html_sidebars = { '**': [] -} \ No newline at end of file +} From c41e22f25b73e5f06915140649d57017a27cc886 Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:06:40 +0200 Subject: [PATCH 7/8] Removed caption --- docs/source/tutorials.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/tutorials.md b/docs/source/tutorials.md index 8e9b07e..84e10de 100644 --- a/docs/source/tutorials.md +++ b/docs/source/tutorials.md @@ -1,8 +1,9 @@ # Tutorials +Here are a few tutorials to help you get started. + ```{toctree} :maxdepth: 1 -:caption: Tutorials :glob: tutorials/* \ No newline at end of file From aa23e657b68ffe71c9a2cd838019d67ad73672ab Mon Sep 17 00:00:00 2001 From: Max Date: Sun, 14 Sep 2025 10:07:45 +0200 Subject: [PATCH 8/8] Added sphinx_bootstrap_theme to deps --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index e8e824f..15f873c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,6 +43,7 @@ optional-dependencies.docs = [ "pyproject-fmt", "sphinx", "sphinx-rtd-theme", + "sphinx_bootstrap_theme", ] optional-dependencies.test = [ "coverage", "pytest" ] urls."Source" = "https://github.com/max-models/template-python"