Skip to content

Commit 6c1da55

Browse files
enryHenryH
committed
✨ basic docs
- file content organization still to fix
1 parent bcd91ad commit 6c1da55

File tree

6 files changed

+228
-133
lines changed

6 files changed

+228
-133
lines changed

‎docs/.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# apidocs
2+
reference
3+
# builds
4+
_build
5+
quarto_report
6+
logs
7+
jupyter_execute

‎docs/README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Docs creation
2+
3+
In order to build the docs you need to
4+
5+
1. install sphinx and additional support packages
6+
2. build the package reference files
7+
3. run sphinx to create a local html version
8+
9+
The documentation is build using readthedocs automatically.
10+
11+
Install the docs dependencies of the package (as speciefied in toml):
12+
13+
```bash
14+
# in main folder
15+
# pip install ".[docs]"
16+
poetry install --with docs
17+
```
18+
19+
## Build docs using Sphinx command line tools
20+
21+
Command to be run from `path/to/docs`, i.e. from within the `docs` package folder:
22+
23+
Options:
24+
- `--separate` to build separate pages for each (sub-)module
25+
26+
```bash
27+
# pwd: docs
28+
# apidoc
29+
sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../vuegen
30+
# build docs
31+
sphinx-build -n -W --keep-going -b html ./ ./_build/
32+
```

‎docs/conf.py‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
import os
14+
from importlib import metadata
15+
16+
# -- Project information -----------------------------------------------------
17+
18+
project = "mockup"
19+
copyright = "2024, Multiomics-Analytics-Group"
20+
author = "Multiomics-Analytics-Group, Sebastián Ayala Ruano, Henry Webel, Alberto Santos"
21+
PACKAGE_VERSION = metadata.version("vuegen")
22+
version = PACKAGE_VERSION
23+
release = PACKAGE_VERSION
24+
25+
26+
# -- General configuration ---------------------------------------------------
27+
28+
# Add any Sphinx extension module names here, as strings. They can be
29+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
30+
# ones.
31+
extensions = [
32+
"sphinx.ext.autodoc",
33+
"sphinx.ext.autodoc.typehints",
34+
"sphinx.ext.viewcode",
35+
"sphinx.ext.napoleon",
36+
"sphinx.ext.intersphinx",
37+
"sphinx_new_tab_link",
38+
"myst_nb",
39+
]
40+
41+
# https://myst-nb.readthedocs.io/en/latest/computation/execute.html
42+
nb_execution_mode = "auto"
43+
44+
myst_enable_extensions = ["dollarmath", "amsmath"]
45+
46+
# Plolty support through require javascript library
47+
# https://myst-nb.readthedocs.io/en/latest/render/interactive.html#plotly
48+
html_js_files = [
49+
"https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"
50+
]
51+
52+
# https://myst-nb.readthedocs.io/en/latest/configuration.html
53+
# Execution
54+
nb_execution_raise_on_error = True
55+
# Rendering
56+
nb_merge_streams = True
57+
58+
# https://myst-nb.readthedocs.io/en/latest/authoring/custom-formats.html#write-custom-formats
59+
# ! if you use it, then you cannot directly execute the notebook in the browser in colab
60+
# (the file needs to be fetched from the repository)
61+
# just keep both syncing it using papermill
62+
# nb_custom_formats = {".py": ["jupytext.reads", {"fmt": "py:percent"}]}
63+
64+
# Add any paths that contain templates here, relative to this directory.
65+
templates_path = ["_templates"]
66+
67+
# List of patterns, relative to source directory, that match files and
68+
# directories to ignore when looking for source files.
69+
# This pattern also affects html_static_path and html_extra_path.
70+
exclude_patterns = [
71+
"_build",
72+
"Thumbs.db",
73+
".DS_Store",
74+
"jupyter_execute",
75+
"conf.py",
76+
]
77+
78+
79+
# Intersphinx options
80+
intersphinx_mapping = {
81+
"python": ("https://docs.python.org/3", None),
82+
# "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
83+
# "scikit-learn": ("https://scikit-learn.org/stable/", None),
84+
# "matplotlib": ("https://matplotlib.org/stable/", None),
85+
}
86+
87+
# -- Options for HTML output -------------------------------------------------
88+
89+
# The theme to use for HTML and HTML Help pages. See the documentation for
90+
# a list of builtin themes.
91+
# See:
92+
# https://github.com/executablebooks/MyST-NB/blob/master/docs/conf.py
93+
# html_title = ""
94+
html_theme = "sphinx_book_theme"
95+
# html_logo = "_static/logo-wide.svg"
96+
# html_favicon = "_static/logo-square.svg"
97+
html_theme_options = {
98+
"github_url": "https://github.com/Multiomics-Analytics-Group/vuegen",
99+
"repository_url": "https://github.com/Multiomics-Analytics-Group/vuegen",
100+
"repository_branch": "main",
101+
"home_page_in_toc": True,
102+
"path_to_docs": "docs",
103+
"show_navbar_depth": 1,
104+
"use_edit_page_button": True,
105+
"use_repository_button": True,
106+
"use_download_button": True,
107+
"launch_buttons": {
108+
"colab_url": "https://colab.research.google.com"
109+
# "binderhub_url": "https://mybinder.org",
110+
# "notebook_interface": "jupyterlab",
111+
},
112+
"navigation_with_keys": False,
113+
}
114+
115+
# Add any paths that contain custom static files (such as style sheets) here,
116+
# relative to this directory. They are copied after the builtin static files,
117+
# so a file named "default.css" will overwrite the builtin "default.css".
118+
# html_static_path = ["_static"]
119+
120+
121+
# -- Setup for sphinx-apidoc -------------------------------------------------
122+
123+
# Read the Docs doesn't support running arbitrary commands like tox.
124+
# sphinx-apidoc needs to be called manually if Sphinx is running there.
125+
# https://github.com/readthedocs/readthedocs.org/issues/1139
126+
127+
if os.environ.get("READTHEDOCS") == "True":
128+
from pathlib import Path
129+
130+
PROJECT_ROOT = Path(__file__).parent.parent
131+
PACKAGE_ROOT = PROJECT_ROOT / "vuegen"
132+
133+
def run_apidoc(_):
134+
from sphinx.ext import apidoc
135+
136+
apidoc.main(
137+
[
138+
"--force",
139+
"--implicit-namespaces",
140+
"--module-first",
141+
"--separate",
142+
"-o",
143+
str(PROJECT_ROOT / "docs" / "reference"),
144+
str(PACKAGE_ROOT),
145+
str(PACKAGE_ROOT / "*.c"),
146+
str(PACKAGE_ROOT / "*.so"),
147+
]
148+
)
149+
150+
def setup(app):
151+
app.connect("builder-inited", run_apidoc)

‎docs/index.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. include:: ../README.md
2+
:parser: myst_parser.sphinx_
3+
:start-line: 0
4+
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
:caption: Modules
9+
:hidden:
10+
11+
reference/vuegen
12+
13+
14+
.. toctree::
15+
:maxdepth: 1
16+
:caption: MISC:
17+
:hidden:
18+
19+
README.md

‎docs/vuegen_demo.ipynb‎

Lines changed: 9 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -21,25 +21,12 @@
2121
},
2222
{
2323
"cell_type": "code",
24-
"execution_count": 1,
24+
"execution_count": null,
2525
"metadata": {},
2626
"outputs": [],
2727
"source": [
28-
"import sys\n",
29-
"import os \n",
30-
"# Get the absolute path to the root directory\n",
31-
"working_dir = os.getcwd()\n",
32-
"project_root = os.path.abspath(os.path.join(working_dir, '..'))\n",
33-
"\n",
34-
"# Check if the current directory is \"docs\" and change to project_root if true\n",
35-
"if os.path.basename(working_dir) == 'docs':\n",
36-
" os.chdir(project_root)\n",
37-
"\n",
38-
"# Add vuegen to the Python path\n",
39-
"sys.path.append(os.path.join(project_root, 'vuegen'))\n",
40-
"\n",
41-
"import report_generator\n",
42-
"from utils import get_logger, load_yaml_config"
28+
"from vuegen import report_generator\n",
29+
"from vuegen.utils import get_logger, load_yaml_config"
4330
]
4431
},
4532
{
@@ -60,123 +47,12 @@
6047
},
6148
{
6249
"cell_type": "code",
63-
"execution_count": 4,
50+
"execution_count": null,
6451
"metadata": {},
65-
"outputs": [
66-
{
67-
"name": "stdout",
68-
"output_type": "stream",
69-
"text": [
70-
"[2024-12-02 12:18:51,947] root: INFO - Path to log file: logs/2024122_121851_html_report_None.log\n",
71-
"[2024-12-02 12:18:51,948] root: INFO - Report 'MicW2Graph' initialized with 3 sections.\n",
72-
"[2024-12-02 12:18:51,948] root: DEBUG - Generating 'html' report in directory: 'quarto_report'\n",
73-
"[2024-12-02 12:18:51,949] root: DEBUG - Output directory already existed: 'quarto_report'\n",
74-
"[2024-12-02 12:18:51,949] root: INFO - Output directory for static content already existed: 'quarto_report/static'\n",
75-
"[2024-12-02 12:18:51,950] root: INFO - Starting to generate sections for the report.\n",
76-
"[2024-12-02 12:18:51,950] root: DEBUG - Processing section: 'Exploratory Data Analysis' - 3 subsection(s)\n",
77-
"[2024-12-02 12:18:51,951] root: DEBUG - Processing subsection: 'Abundance data' - 4 component(s)\n",
78-
"[2024-12-02 12:18:51,951] root: INFO - Successfully generated content for plot: 'Top 5 species by biome (plotly)'\n",
79-
"[2024-12-02 12:18:51,952] root: INFO - Successfully generated content for plot: 'Multiline plot (altair)'\n",
80-
"[2024-12-02 12:18:51,952] root: INFO - Successfully generated content for DataFrame: 'Abundance data for all studies (csv)'\n",
81-
"[2024-12-02 12:18:51,953] root: INFO - Successfully generated content for DataFrame: 'Abundance data for all studies (excel)'\n",
82-
"[2024-12-02 12:18:51,953] root: INFO - Generated content and imports for subsection: 'Abundance data'\n",
83-
"[2024-12-02 12:18:51,954] root: DEBUG - Processing subsection: 'Sample data' - 4 component(s)\n",
84-
"[2024-12-02 12:18:51,955] root: INFO - Successfully generated content for plot: 'Number of samples per study (png)'\n",
85-
"[2024-12-02 12:18:51,955] root: INFO - Successfully generated content for plot: 'Sampling countries for all studies (plotly)'\n",
86-
"[2024-12-02 12:18:51,955] root: INFO - Successfully generated content for DataFrame: 'Sample data for all studies (txt)'\n",
87-
"[2024-12-02 12:18:51,956] root: INFO - Successfully generated content for DataFrame: 'Sample data for all studies (parquet)'\n",
88-
"[2024-12-02 12:18:51,956] root: INFO - Generated content and imports for subsection: 'Sample data'\n",
89-
"[2024-12-02 12:18:51,957] root: DEBUG - Processing subsection: 'Extra information' - 1 component(s)\n",
90-
"[2024-12-02 12:18:51,958] root: INFO - Successfully generated content for Markdown: 'Markdown example'\n",
91-
"[2024-12-02 12:18:51,959] root: INFO - Generated content and imports for subsection: 'Extra information'\n",
92-
"[2024-12-02 12:18:51,959] root: DEBUG - Processing section: 'Microbial Association Networks' - 3 subsection(s)\n",
93-
"[2024-12-02 12:18:51,960] root: DEBUG - Processing subsection: 'Network Visualization1' - 1 component(s)\n",
94-
"[2024-12-02 12:18:51,963] root: INFO - Successfully read network from file: example_data/MicW2Graph/man_example.graphml.\n",
95-
"[2024-12-02 12:18:51,979] root: INFO - PyVis network created and saved as: quarto_report/static/Network1_(graphml).html.\n",
96-
"[2024-12-02 12:18:51,980] root: INFO - Successfully generated content for plot: 'Network1 (graphml)'\n",
97-
"[2024-12-02 12:18:51,980] root: INFO - Generated content and imports for subsection: 'Network Visualization1'\n",
98-
"[2024-12-02 12:18:51,980] root: DEBUG - Processing subsection: 'Network Visualization2' - 1 component(s)\n",
99-
"[2024-12-02 12:18:51,983] root: INFO - Successfully read network from file: example_data/MicW2Graph/man_example.csv.\n",
100-
"[2024-12-02 12:18:51,994] root: INFO - PyVis network created and saved as: quarto_report/static/Network2_(edge_list_csv).html.\n",
101-
"[2024-12-02 12:18:51,994] root: INFO - Successfully generated content for plot: 'Network2 (edge list csv)'\n",
102-
"[2024-12-02 12:18:51,994] root: INFO - Generated content and imports for subsection: 'Network Visualization2'\n",
103-
"[2024-12-02 12:18:51,995] root: DEBUG - Processing subsection: 'Edge list' - 1 component(s)\n",
104-
"[2024-12-02 12:18:51,995] root: INFO - Successfully generated content for DataFrame: 'Edge list (csv)'\n",
105-
"[2024-12-02 12:18:51,995] root: INFO - Generated content and imports for subsection: 'Edge list'\n",
106-
"[2024-12-02 12:18:51,995] root: DEBUG - Processing section: 'APICall test' - 1 subsection(s)\n",
107-
"[2024-12-02 12:18:51,996] root: DEBUG - Processing subsection: 'Simple test' - 1 component(s)\n",
108-
"[2024-12-02 12:18:51,996] root: WARNING - Unsupported component type 'apicall' in subsection: Simple test\n",
109-
"[2024-12-02 12:18:51,996] root: INFO - Generated content and imports for subsection: 'Simple test'\n",
110-
"[2024-12-02 12:18:51,997] root: INFO - Created qmd script to render the app: quarto_report.qmd\n"
111-
]
112-
},
113-
{
114-
"name": "stderr",
115-
"output_type": "stream",
116-
"text": [
117-
"\n",
118-
"Starting python3 kernel...Done\n",
119-
"\n",
120-
"Executing 'quarto_report.quarto_ipynb'\n",
121-
" Cell 1/10: 'Imports'.......................................Done\n",
122-
" Cell 2/10: 'Top 5 species by biome (plotly)'...............Done\n",
123-
" Cell 3/10: 'Multiline plot (altair)'.......................Done\n",
124-
" Cell 4/10: 'Abundance data for all studies (csv)'..........Done\n",
125-
" Cell 5/10: 'Abundance data for all studies (excel)'........Done\n",
126-
" Cell 6/10: 'Sampling countries for all studies (plotly)'...Done\n",
127-
" Cell 7/10: 'Sample data for all studies (txt)'.............Done\n",
128-
" Cell 8/10: 'Sample data for all studies (parquet)'.........Done\n",
129-
" Cell 9/10: 'Markdown example'..............................Done\n",
130-
" Cell 10/10: 'Edge list (csv)'...............................Done\n",
131-
"\n",
132-
"\u001b[1mpandoc \u001b[22m\n",
133-
" to: html\n",
134-
" output-file: quarto_report.html\n",
135-
" standalone: true\n",
136-
" self-contained: true\n",
137-
" section-divs: true\n",
138-
" html-math-method: mathjax\n",
139-
" wrap: none\n",
140-
" default-image-extension: png\n",
141-
" toc: true\n",
142-
" toc-depth: 3\n",
143-
" \n",
144-
"\u001b[1mmetadata\u001b[22m\n",
145-
" document-css: false\n",
146-
" link-citations: true\n",
147-
" date-format: long\n",
148-
" lang: en\n",
149-
" title: MicW2Graph\n",
150-
" toc-location: left\n",
151-
" page-layout: full\n",
152-
" \n",
153-
"\u001b[33mWARNING (/Applications/quarto/share/filters/main.lua:9305) Unable to parse table from raw html block: skipping.\n",
154-
"\u001b[39m\u001b[33mWARNING (/Applications/quarto/share/filters/main.lua:9305) Unable to parse table from raw html block: skipping.\n",
155-
"\u001b[39m\u001b[33mWARNING (/Applications/quarto/share/filters/main.lua:9305) Unable to parse table from raw html block: skipping.\n",
156-
"\u001b[39m\u001b[33mWARNING (/Applications/quarto/share/filters/main.lua:9305) Unable to parse table from raw html block: skipping.\n",
157-
"\u001b[39m\u001b[33mWARNING (/Applications/quarto/share/filters/main.lua:9305) Unable to parse table from raw html block: skipping.\n",
158-
"\u001b[39m"
159-
]
160-
},
161-
{
162-
"name": "stdout",
163-
"output_type": "stream",
164-
"text": [
165-
"[2024-12-02 12:19:01,988] root: INFO - 'MicW2Graph' 'html' report rendered\n"
166-
]
167-
},
168-
{
169-
"name": "stderr",
170-
"output_type": "stream",
171-
"text": [
172-
"Output created: quarto_report.html\n",
173-
"\n"
174-
]
175-
}
176-
],
52+
"outputs": [],
17753
"source": [
17854
"# Load the YAML configuration file with the report metadata\n",
179-
"config_path = \"report_config_micw2graph.yaml\"\n",
55+
"config_path = \"../example_data/MicW2Graph/report_config_micw2graph.yaml\"\n",
18056
"report_config = load_yaml_config(config_path)\n",
18157
"\n",
18258
"# Define logger suffix based on report engine, type and name\n",
@@ -187,13 +63,13 @@
18763
"logger = get_logger(f\"{report_type}_report_{report_name}\")\n",
18864
"\n",
18965
"# Generate the report\n",
190-
"report_generator.get_report(config = report_config, report_type = report_type, logger = logger)"
66+
"# report_generator.get_report(config = report_config, report_type = report_type, logger = logger)"
19167
]
19268
}
19369
],
19470
"metadata": {
19571
"kernelspec": {
196-
"display_name": "report-generator-IFxaxej_-py3.12",
72+
"display_name": "vuegen",
19773
"language": "python",
19874
"name": "python3"
19975
},
@@ -207,7 +83,7 @@
20783
"name": "python",
20884
"nbconvert_exporter": "python",
20985
"pygments_lexer": "ipython3",
210-
"version": "3.12.6"
86+
"version": "3.9.21"
21187
}
21288
},
21389
"nbformat": 4,

0 commit comments

Comments
 (0)