Docs restructuring (#101)

* General structure revamp

* Added missing __init__.py and fixed links in sweep.md

* Fixed formatting of data_formats

* moved from autoapi into the sphinx supported extensions

* Removed old mkdocs.yml

* switched action trigger

* Added requirements to pyproject.toml

* fixing sphinx.yml typo

* Fixed failed built due to dependencies

Author: marcosfrenkel

.github/workflows/sphinx.yml

@@ -1,6 +1,12 @@
 name: "Sphinx: Render docs"
 
-on: push
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
   build:

.gitignore

@@ -71,7 +71,9 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/build/
-docs/autoapi/
+# These files are generated automatically by autosummary
+docs/**/*.rst
+docs/**/generated
 site/
 
 # PyBuilder

docs/Makefile

@@ -12,7 +12,12 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile clean
+
+# Custom clean target to also remove autosummary-generated files
+clean:
+	rm -rf api/generated/
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/api/index.md

@@ -0,0 +1,14 @@
+# API Reference
+
+Complete API documentation for Labcore, generated from docstrings.
+
+```{eval-rst}
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   labcore.data
+   labcore.measurement
+   labcore.analysis
+   labcore.utils
+```

docs/conf.py

@@ -20,12 +20,12 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    'myst_parser',           # Markdown support
-    'sphinx.ext.autodoc',    # API documentation from docstrings
-    'sphinx.ext.napoleon',   # Support for NumPy and Google style docstrings
-    'sphinx.ext.viewcode',   # Add links to source code
-    'autoapi.extension',     # Automatic API documentation generation
-    'nbsphinx',              # Jupyter notebook support
+    'myst_parser',            # Markdown support
+    'sphinx.ext.autodoc',     # API documentation from docstrings
+    'sphinx.ext.autosummary', # Generate summary tables for modules
+    'sphinx.ext.napoleon',    # Support for NumPy and Google style docstrings
+    'sphinx.ext.viewcode',    # Add links to source code
+    'nbsphinx',               # Jupyter notebook support
     'sphinx.ext.intersphinx', # Link to other project docs
 ]
 
@@ -44,19 +44,22 @@
     "tasklist",         # Task lists
 ]
 
-# AutoAPI Configuration (replaces mkdocstrings)
-autoapi_type = 'python'
-autoapi_dirs = ['../labcore']
-autoapi_options = [
-    'members',
-    'undoc-members',
-    'show-inheritance',
-    'show-module-summary',
-    'imported-members',
-]
-autoapi_keep_files = False
-autoapi_add_toctree_entry = True
-autoapi_python_class_content = 'both'  # Include both class and __init__ docstrings
+# Allow MyST to parse Sphinx roles and directives
+myst_enable_roles = True
+
+# Autosummary configuration (auto-generate API docs)
+autosummary_generate = True
+autosummary_generate_overwrite = True
+
+# Autodoc configuration (required for proper cross-references)
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': False,
+    'show-inheritance': True,
+}
+
+# MyST configuration for proper cross-references in Markdown
+myst_linkify_fuzzy_links = True
 
 # nbsphinx configuration (for Jupyter notebooks)
 nbsphinx_execute = 'never'  # Don't execute notebooks during build (safer)
@@ -89,6 +92,7 @@
 html_baseurl = 'https://toolsforexperiments.github.io/labcore/'
 
 html_theme_options = {
+    "show_nav_level": 2,
     "logo": {
         "text": "Labcore",
     },

docs/first_steps/first_analysis.md

@@ -0,0 +1,3 @@
+# Basic Analysis 
+
+The following will be an introductory guide on how to perform analysis.

docs/first_steps/first_data.md

@@ -0,0 +1,7 @@
+# Creating Basic Datasets
+
+Here will go how to create the first datasets with basic sweeps.
+
+File structure in disk.
+
+How to load it and use it.

docs/first_steps/index.md

@@ -0,0 +1,9 @@
+# First Steps
+
+The following pages will help you get familiar with Labcore's tools. They are not meant to be exhaustive but simply an introduction.
+
+```{toctree}
+installation
+first_data
+first_analysis
+```

docs/first_steps/installation.md

@@ -0,0 +1,3 @@
+# Installation
+
+Here will go the installation details. More to come.

docs/index.md

@@ -37,10 +37,8 @@ Labcore is developed by Physicists for real needs happening inside of our lab.
 :maxdepth: 2
 :caption: Contents
 
-instruments/index
-measurement/index
-data/index
-about
+first_steps/index
+user_guide/index
 ```
 
 ## Examples
@@ -60,5 +58,5 @@ The API documentation is automatically generated from the source code.
 :maxdepth: 1
 :caption: API Reference
 
-autoapi/index
+api/index
 ```