From 26faef1f229c82ba3d4bf264cda3dfad43de490d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sergio=20S=C3=A1nchez=20Ram=C3=ADrez?=
<15837247+mofeing@users.noreply.github.com>
Date: Fri, 22 Nov 2024 19:37:41 +0100
Subject: [PATCH] Move documentation to Vitepress (#256)
* Update to DocumenterVitepress backend
* Ignore Node packages
* Temporarily disable raw HTML image inclusion
* update alternatives
* big docs update
* more doc changes
* update type hierarchy diagram
* update
* format code
* configure vitepress
* split API into sections
* rename "alternatives" to "friends"
* comment `baseTemp`
* add icons for friends and api sections
* fix versioned docs
* try fix navigation bar
* fix path to versions.js
* add missing import
---
.gitignore | 147 +++++++++-
docs/.gitignore | 4 +
docs/Project.toml | 5 +
docs/make.jl | 53 ++--
docs/package.json | 15 +
docs/src/.vitepress/config.mts | 71 +++++
docs/src/.vitepress/theme/VersionPicker.vue | 55 ++++
docs/src/.vitepress/theme/index.ts | 62 ++++
docs/src/.vitepress/theme/style.css | 266 ++++++++++++++++++
docs/src/alternatives.md | 8 -
docs/src/api/ansatz.md | 7 +
docs/src/{ => api}/quantum.md | 18 +-
docs/src/api/tensor.md | 11 +
docs/src/api/tensornetwork.md | 33 +++
docs/src/developer/cached-field.md | 1 +
docs/src/developer/hypergraph.md | 0
docs/src/developer/keyword-dispatch.md | 0
docs/src/developer/type-hierarchy.md | 34 ++-
docs/src/developer/unsafe-region.md | 9 +
docs/src/friends.md | 9 +
docs/src/index.md | 60 +++-
docs/src/manual/ansatz/index.md | 1 +
.../{ansatz/chain.md => manual/ansatz/mps.md} | 5 -
docs/src/{ => manual}/ansatz/product.md | 0
docs/src/{ => manual}/contraction.md | 0
docs/src/manual/quantum.md | 5 +
docs/src/manual/tensor-network.md | 25 ++
docs/src/{ => manual}/tensors.md | 26 +-
docs/src/{ => manual}/transformations.md | 30 --
docs/src/tensor-network.md | 67 -----
30 files changed, 823 insertions(+), 204 deletions(-)
create mode 100644 docs/.gitignore
create mode 100644 docs/package.json
create mode 100644 docs/src/.vitepress/config.mts
create mode 100644 docs/src/.vitepress/theme/VersionPicker.vue
create mode 100644 docs/src/.vitepress/theme/index.ts
create mode 100644 docs/src/.vitepress/theme/style.css
delete mode 100644 docs/src/alternatives.md
create mode 100644 docs/src/api/ansatz.md
rename docs/src/{ => api}/quantum.md (67%)
create mode 100644 docs/src/api/tensor.md
create mode 100644 docs/src/api/tensornetwork.md
create mode 100644 docs/src/developer/cached-field.md
create mode 100644 docs/src/developer/hypergraph.md
create mode 100644 docs/src/developer/keyword-dispatch.md
create mode 100644 docs/src/developer/unsafe-region.md
create mode 100644 docs/src/friends.md
create mode 100644 docs/src/manual/ansatz/index.md
rename docs/src/{ansatz/chain.md => manual/ansatz/mps.md} (97%)
rename docs/src/{ => manual}/ansatz/product.md (100%)
rename docs/src/{ => manual}/contraction.md (100%)
create mode 100644 docs/src/manual/quantum.md
create mode 100644 docs/src/manual/tensor-network.md
rename docs/src/{ => manual}/tensors.md (87%)
rename docs/src/{ => manual}/transformations.md (93%)
delete mode 100644 docs/src/tensor-network.md
diff --git a/.gitignore b/.gitignore
index 0914aac99..e9fd35e65 100644
--- a/.gitignore
+++ b/.gitignore
@@ -120,15 +120,6 @@ $RECYCLE.BIN/
# Windows shortcuts
*.lnk
-# End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,linux,julia,macos,windows
-
-# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
-.vscode/settings.json
-.julia
-*.excalidraw
-archive/
-test/.CondaPkg/
-
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
@@ -291,3 +282,141 @@ cython_debug/
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)
+.vscode/settings.json
+.julia
+*.excalidraw
+archive/
+test/.CondaPkg/
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..0587d7400
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,4 @@
+build/
+node_modules/
+package-lock.json
+Manifest.toml
\ No newline at end of file
diff --git a/docs/Project.toml b/docs/Project.toml
index 6ac2a8e16..b2c25ef34 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -2,12 +2,17 @@
CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
EinExprs = "b1794770-133b-4de1-afb4-526377e9f4c5"
GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"
+Kroki = "b3565e16-c1f2-4fe9-b4ab-221c88942068"
Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
NetworkLayout = "46757867-2c16-5918-afeb-47bfcb05e46a"
Tenet = "85d41934-b9cd-44e1-8730-56d86f15f3ec"
+[sources]
+Tenet = {path = "/Users/mofeing/Developer/Tenet.jl/docs/.."}
+
[compat]
Documenter = "1"
DocumenterCitations = "1.2"
diff --git a/docs/make.jl b/docs/make.jl
index 681c099e7..0474b13f7 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,9 +1,5 @@
-using Pkg
-Pkg.activate(@__DIR__)
-Pkg.develop(; path=joinpath(@__DIR__, ".."))
-Pkg.instantiate()
-
using Documenter
+using DocumenterVitepress
using DocumenterCitations
using Tenet
using CairoMakie
@@ -18,28 +14,45 @@ makedocs(;
modules=[Tenet, Base.get_extension(Tenet, :TenetGraphMakieExt)],
sitename="Tenet.jl",
authors="Sergio Sánchez Ramírez and contributors",
- pages=Any[
+ pages=[
"Home" => "index.md",
- "Tensors" => "tensors.md",
- "Tensor Networks" => "tensor-network.md",
- "Contraction" => "contraction.md",
- "Transformations" => "transformations.md",
- "Quantum" => [
- "Introduction" => "quantum.md",
- "Ansatzes" => ["`Product` ansatz" => "ansatz/product.md", "`Chain` ansatz" => "ansatz/chain.md"],
+ "📖 Manual" => [
+ "Tensors" => "manual/tensors.md",
+ "Tensor Networks" => "manual/tensor-network.md",
+ "Contraction" => "manual/contraction.md",
+ "Transformations" => "manual/transformations.md",
+ "Quantum" => "manual/quantum.md",
+ "Ansatz" => [
+ "Introduction" => "manual/ansatz/index.md",
+ "Product ansatz" => "manual/ansatz/product.md",
+ "MPS/MPO ansatz" => "manual/ansatz/mps.md",
+ ],
+ "Visualization" => "visualization.md",
+ ],
+ "🫂 Friends" => "friends.md",
+ "🧭 API" => [
+ "Tensor" => "api/tensor.md",
+ "TensorNetwork" => "api/tensornetwork.md",
+ "Quantum" => "api/quantum.md",
+ "Ansatz" => "api/ansatz.md",
+ ],
+ "⚒️ Developer Reference" => [
+ "Hypergraph representation of `TensorNetwork`" => "developer/hypergraph.md",
+ "Type Hierarchy" => "developer/type-hierarchy.md",
+ "Unsafe region" => "developer/unsafe-region.md",
+ "Cached field" => "developer/cached-field.md",
+ "Keyword Dispatch" => "developer/keyword-dispatch.md",
],
- "Visualization" => "visualization.md",
- "Alternatives" => "alternatives.md",
- "References" => "references.md",
- "⚒️ Developer Reference" => ["`TensorNetwork` type hierarchy" => "developer/type-hierarchy.md"],
],
pagesonly=true,
- format=Documenter.HTML(;
- prettyurls=false, assets=["assets/favicon.ico", "assets/citations.css", "assets/youtube.css"]
+ format=DocumenterVitepress.MarkdownVitepress(;
+ repo="https://github.com/bsc-quantic/Tenet.jl",
+ assets=["assets/favicon.ico", "assets/citations.css", "assets/youtube.css"],
+ # build_vitepress=false,
),
plugins=[bib],
checkdocs=:exports,
warnonly=true,
)
-deploydocs(; repo="github.com/bsc-quantic/Tenet.jl.git", devbranch="master", push_preview=true)
+deploydocs(; repo="github.com/bsc-quantic/Tenet.jl.git", target="build", devbranch="master", push_preview=true)
diff --git a/docs/package.json b/docs/package.json
new file mode 100644
index 000000000..5633b4976
--- /dev/null
+++ b/docs/package.json
@@ -0,0 +1,15 @@
+{
+ "scripts": {
+ "docs:dev": "vitepress dev build/.documenter",
+ "docs:build": "vitepress build build/.documenter",
+ "docs:preview": "vitepress preview build/.documenter"
+ },
+ "dependencies": {
+ "@shikijs/transformers": "^1.1.7",
+ "markdown-it": "^14.1.0",
+ "markdown-it-footnote": "^4.0.0",
+ "markdown-it-mathjax3": "^4.3.2",
+ "vitepress": "^1.1.4",
+ "vitepress-plugin-tabs": "^0.5.0"
+ }
+}
diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts
new file mode 100644
index 000000000..bdb14a1c3
--- /dev/null
+++ b/docs/src/.vitepress/config.mts
@@ -0,0 +1,71 @@
+import { defineConfig } from 'vitepress'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
+import mathjax3 from "markdown-it-mathjax3";
+import footnote from "markdown-it-footnote";
+
+const baseTemp = {
+ base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+}
+
+const navTemp = {
+ nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+}
+
+const nav = [
+ ...navTemp.nav,
+ {
+ component: 'VersionPicker'
+ }
+]
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+ base: baseTemp.base,
+ title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+ description: 'Documentation of Tenet.jl library',
+ lastUpdated: true,
+ cleanUrls: true,
+ outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
+ head: [
+ ['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }],
+ ["script", { src: `/Tenet.jl/versions.js` }],
+ ["script", { src: `${baseTemp.base}siteinfo.js` }],
+ ],
+ ignoreDeadLinks: true,
+
+ markdown: {
+ math: true,
+ config(md) {
+ md.use(tabsMarkdownPlugin),
+ md.use(mathjax3),
+ md.use(footnote)
+ },
+ theme: {
+ light: "github-light",
+ dark: "github-dark"
+ }
+ },
+ themeConfig: {
+ outline: 'deep',
+ logo: {
+ light: '/logo.svg',
+ dark: '/logo-dark.svg',
+ },
+ search: {
+ provider: 'local',
+ options: {
+ detailedView: true
+ }
+ },
+ nav,
+ sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+ editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+ socialLinks: [
+ { icon: 'github', link: 'REPLACE_ME_DOCUMENTER_VITEPRESS' }
+ ],
+ footer: {
+ message: 'Made with DocumenterVitepress.jl
+
+
+
\ No newline at end of file
diff --git a/docs/src/.vitepress/theme/index.ts b/docs/src/.vitepress/theme/index.ts
new file mode 100644
index 000000000..d7b0b0a2f
--- /dev/null
+++ b/docs/src/.vitepress/theme/index.ts
@@ -0,0 +1,62 @@
+// .vitepress/theme/index.ts
+import { h, watch } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import VersionPicker from "./VersionPicker.vue"
+
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+import './style.css'
+
+export default {
+ extends: DefaultTheme,
+ Layout() {
+ return h(DefaultTheme.Layout, null, {
+ // https://vitepress.dev/guide/extending-default-theme#layout-slots
+ })
+ },
+ enhanceApp({ app, router, siteData }) {
+ enhanceAppWithTabs(app)
+ app.component('VersionPicker', VersionPicker);
+ // Only run this on the client. Not during build.
+ // this function replaces the version in the URL with the stable prefix whenever a
+ // new route is navigated to. VitePress does not support relative links all over the site,
+ // so urls will go to v0.XY even if we start at stable. This solution is not ideal as
+ // there is a noticeable delay between navigating to a new page and editing the url, but it's
+ // currently better than nothing, as users are bound to copy versioned links to the docs otherwise
+ // which will lead users to outdated docs in the future.
+ if (typeof window !== "undefined") {
+ function rewriteURL() {
+ // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE
+ // in siteinfo.js.
+ if (
+ window.DOCUMENTER_NEWEST === undefined ||
+ window.DOCUMENTER_CURRENT_VERSION === undefined ||
+ window.DOCUMENTER_STABLE === undefined
+ ) {
+ return;
+ }
+
+ // Current version is newest version, so we can rewrite the url
+ if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) {
+ const rewritten_url = window.location.href.replace(
+ window.DOCUMENTER_CURRENT_VERSION,
+ window.DOCUMENTER_STABLE
+ );
+ window.history.replaceState(
+ { additionalInformation: "URL rewritten to stable" },
+ "Makie",
+ rewritten_url
+ );
+ return;
+ }
+ }
+
+ // rewrite on router changes through vitepress
+ watch(() => router.route.data.relativePath, rewriteURL, {
+ immediate: true,
+ });
+ // also rewrite at initial load
+ document.addEventListener("DOMContentLoaded", rewriteURL);
+ }
+ }
+} satisfies Theme
\ No newline at end of file
diff --git a/docs/src/.vitepress/theme/style.css b/docs/src/.vitepress/theme/style.css
new file mode 100644
index 000000000..fedc81ed5
--- /dev/null
+++ b/docs/src/.vitepress/theme/style.css
@@ -0,0 +1,266 @@
+/* Customize default theme styling by overriding CSS variables:
+https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/* Layouts */
+
+/*
+ :root {
+ --vp-layout-max-width: 1440px;
+} */
+
+.VPHero .clip {
+ white-space: pre;
+ max-width: 500px;
+}
+
+/* Fonts */
+
+@font-face {
+ font-family: JuliaMono-Regular;
+ src: url("https://cdn.jsdelivr.net/gh/cormullion/juliamono/webfonts/JuliaMono-Regular.woff2");
+}
+
+:root {
+ /* Typography */
+ --vp-font-family-base: "Barlow", "Inter var experimental", "Inter var",
+ -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu,
+ Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
+
+ /* Code Snippet font */
+ --vp-font-family-mono: JuliaMono-Regular, monospace;
+
+}
+
+/*
+Disable contextual alternates (kind of like ligatures but different) in monospace,
+which turns `/>` to an up arrow and `|>` (the Julia pipe symbol) to an up arrow as well.
+This is pretty bad for Julia folks reading even though copy+paste retains the same text.
+*/
+/* Target elements with class 'mono' */
+.mono-no-substitutions {
+ font-family: "JuliaMono-Light", monospace;
+ font-feature-settings: "calt" off;
+}
+
+/* Alternatively, you can use the following if you prefer: */
+.mono-no-substitutions-alt {
+ font-family: "JuliaMono-Light", monospace;
+ font-variant-ligatures: none;
+}
+
+/* If you want to apply this globally to all monospace text: */
+pre,
+code {
+ font-family: "JuliaMono-Light", monospace;
+ font-feature-settings: "calt" off;
+}
+
+/* Colors */
+
+:root {
+ --julia-blue: #4063D8;
+ --julia-purple: #9558B2;
+ --julia-red: #CB3C33;
+ --julia-green: #389826;
+
+ --vp-c-brand: #389826;
+ --vp-c-brand-light: #3dd027;
+ --vp-c-brand-lighter: #9499ff;
+ --vp-c-brand-lightest: #bcc0ff;
+ --vp-c-brand-dark: #535bf2;
+ --vp-c-brand-darker: #454ce1;
+ --vp-c-brand-dimm: #212425;
+}
+
+/* Component: Button */
+
+:root {
+ --vp-button-brand-border: var(--vp-c-brand-light);
+ --vp-button-brand-text: var(--vp-c-white);
+ --vp-button-brand-bg: var(--vp-c-brand);
+ --vp-button-brand-hover-border: var(--vp-c-brand-light);
+ --vp-button-brand-hover-text: var(--vp-c-white);
+ --vp-button-brand-hover-bg: var(--vp-c-brand-light);
+ --vp-button-brand-active-border: var(--vp-c-brand-light);
+ --vp-button-brand-active-text: var(--vp-c-white);
+ --vp-button-brand-active-bg: var(--vp-button-brand-bg);
+}
+
+/* Component: Home */
+
+:root {
+ --vp-home-hero-name-color: transparent;
+ --vp-home-hero-name-background: -webkit-linear-gradient(120deg,
+ #9558B2 30%,
+ #CB3C33);
+
+ --vp-home-hero-image-background-image: linear-gradient(-45deg,
+ #9558B2 30%,
+ #389826 30%,
+ #CB3C33);
+ --vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+ :root {
+ --vp-home-hero-image-filter: blur(56px);
+ }
+}
+
+@media (min-width: 960px) {
+ :root {
+ --vp-home-hero-image-filter: blur(72px);
+ }
+}
+
+/* Component: Custom Block */
+
+:root.dark {
+ --vp-custom-block-tip-border: var(--vp-c-brand);
+ --vp-custom-block-tip-text: var(--vp-c-brand-lightest);
+ --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+
+ /* // Tweak the color palette for blacks and dark grays */
+ --vp-c-black: hsl(220 20% 9%);
+ --vp-c-black-pure: hsl(220, 24%, 4%);
+ --vp-c-black-soft: hsl(220 16% 13%);
+ --vp-c-black-mute: hsl(220 14% 17%);
+ --vp-c-gray: hsl(220 8% 56%);
+ --vp-c-gray-dark-1: hsl(220 10% 39%);
+ --vp-c-gray-dark-2: hsl(220 12% 28%);
+ --vp-c-gray-dark-3: hsl(220 12% 23%);
+ --vp-c-gray-dark-4: hsl(220 14% 17%);
+ --vp-c-gray-dark-5: hsl(220 16% 13%);
+
+ /* // Backgrounds */
+ /* --vp-c-bg: hsl(240, 2%, 11%); */
+ --vp-custom-block-info-bg: hsl(220 14% 17%);
+ /* --vp-c-gutter: hsl(220 20% 9%);
+
+ --vp-c-bg-alt: hsl(220 20% 9%);
+ --vp-c-bg-soft: hsl(220 14% 17%);
+ --vp-c-bg-mute: hsl(220 12% 23%);
+ */
+}
+
+/* Component: Algolia */
+
+.DocSearch {
+ --docsearch-primary-color: var(--vp-c-brand) !important;
+}
+
+/* Component: MathJax */
+
+mjx-container>svg {
+ display: block;
+ margin: auto;
+}
+
+mjx-container {
+ padding: 0.5rem 0;
+}
+
+mjx-container {
+ display: inline;
+ margin: auto 2px -2px;
+}
+
+mjx-container>svg {
+ margin: auto;
+ display: inline-block;
+}
+
+/**
+ * Colors links
+ * -------------------------------------------------------------------------- */
+
+:root {
+ --vp-c-brand-1: #CB3C33;
+ --vp-c-brand-2: #CB3C33;
+ --vp-c-brand-3: #CB3C33;
+ --vp-c-sponsor: #ca2971;
+ --vitest-c-sponsor-hover: #c13071;
+}
+
+.dark {
+ --vp-c-brand-1: #91dd33;
+ --vp-c-brand-2: #91dd33;
+ --vp-c-brand-3: #91dd33;
+ --vp-c-sponsor: #91dd33;
+ --vitest-c-sponsor-hover: #e51370;
+}
+
+/**
+ * Change images from light to dark theme
+ * -------------------------------------------------------------------------- */
+
+:root:not(.dark) .dark-only {
+ display: none;
+}
+
+:root:is(.dark) .light-only {
+ display: none;
+}
+
+/* https://bddxg.top/article/note/vitepress优化/一些细节上的优化.html#文档页面调整-加宽 */
+
+.VPDoc.has-aside .content-container {
+ max-width: 100% !important;
+}
+
+.aside {
+ max-width: 200px !important;
+ padding-left: 0 !important;
+}
+
+.VPDoc {
+ padding-top: 15px !important;
+ padding-left: 5px !important;
+
+}
+
+/* This one does the right menu */
+
+.VPDocOutlineItem li {
+ text-overflow: ellipsis;
+ overflow: hidden;
+ white-space: nowrap;
+ max-width: 200px;
+}
+
+.VPNavBar .title {
+ text-overflow: ellipsis;
+ overflow: hidden;
+ white-space: nowrap;
+}
+
+@media (max-width: 960px) {
+ .VPDoc {
+ padding-left: 25px !important;
+ }
+}
+
+/* This one does the left menu */
+
+/* .VPSidebarItem .VPLink p {
+ text-overflow: ellipsis;
+ overflow: hidden;
+ white-space: nowrap;
+ max-width: 200px;
+} */
+
+
+/* Component: Docstring Custom Block */
+
+.jldocstring.custom-block {
+ border: 1px solid var(--vp-c-gray-2);
+ color: var(--vp-c-text-1)
+}
+
+.jldocstring.custom-block summary {
+ font-weight: 700;
+ cursor: pointer;
+ user-select: none;
+ margin: 0 0 8px;
+}
\ No newline at end of file
diff --git a/docs/src/alternatives.md b/docs/src/alternatives.md
deleted file mode 100644
index 54f5cb858..000000000
--- a/docs/src/alternatives.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Alternatives
-
-`Tenet` is strongly opinionated. We acknowledge that it may not suit all cases (although we try 🙂). If your case doesn't fit `Tenet`'s design, you can try the following libraries:
-
-- [quimb](https://github.com/jcmgray/quimb) [gray2018quimb](@cite) Flexible Tensor Network written in Python. Main source of inspiration for `Tenet`.
-- [tenpy](https://github.com/tenpy/tenpy) [hauschild2021tensor](@cite) Tensor Network library written in Python with a strong focus on physics.
-- [ITensors.jl](https://github.com/ITensor/ITensors.jl) [itensor](@cite) Mature Tensor Network framework written in Julia.
-- [tensorkrowch](https://github.com/joserapa98/tensorkrowch) [ramon2023tensorkrowch](@cite) A new Tensor Network library built on top of PyTorch.
diff --git a/docs/src/api/ansatz.md b/docs/src/api/ansatz.md
new file mode 100644
index 000000000..c0af2f953
--- /dev/null
+++ b/docs/src/api/ansatz.md
@@ -0,0 +1,7 @@
+# Ansatz
+
+## MPS
+
+```@docs
+MPS
+```
diff --git a/docs/src/quantum.md b/docs/src/api/quantum.md
similarity index 67%
rename from docs/src/quantum.md
rename to docs/src/api/quantum.md
index 0c8dd0302..ce3e5986d 100644
--- a/docs/src/quantum.md
+++ b/docs/src/api/quantum.md
@@ -1,4 +1,4 @@
-# `Quantum` Tensor Networks
+# Quantum
```@docs
Quantum
@@ -6,34 +6,18 @@ Tenet.TensorNetwork(::Quantum)
Base.adjoint(::Quantum)
sites
nsites
-```
-
-## Queries
-
-```@docs
Tenet.inds(::Quantum; kwargs...)
Tenet.tensors(::Quantum; kwargs...)
-```
-
-## Connecting `Quantum` Tensor Networks
-
-```@docs
inputs
outputs
lanes
ninputs
noutputs
nlanes
-```
-
-```@docs
Socket
socket(::Quantum)
Scalar
State
Operator
-```
-
-```@docs
Base.merge(::Quantum, ::Quantum...)
```
diff --git a/docs/src/api/tensor.md b/docs/src/api/tensor.md
new file mode 100644
index 000000000..50cc9dab1
--- /dev/null
+++ b/docs/src/api/tensor.md
@@ -0,0 +1,11 @@
+# Tensor
+
+```@docs
+Base.parent(::Tensor)
+inds(::Tensor)
+Base.size(::Tensor)
+Tenet.contract(::Tensor, ::Tensor)
+LinearAlgebra.svd(::Tensor)
+LinearAlgebra.qr(::Tensor)
+LinearAlgebra.lu(::Tensor)
+```
diff --git a/docs/src/api/tensornetwork.md b/docs/src/api/tensornetwork.md
new file mode 100644
index 000000000..c2da8f50a
--- /dev/null
+++ b/docs/src/api/tensornetwork.md
@@ -0,0 +1,33 @@
+# TensorNetwork
+
+```@docs
+TensorNetwork
+inds(::Tenet.TensorNetwork)
+size(::Tenet.TensorNetwork)
+tensors(::Tenet.TensorNetwork)
+push!(::Tenet.TensorNetwork, ::Tensor)
+pop!(::Tenet.TensorNetwork, ::Tensor)
+append!(::Tenet.TensorNetwork, ::Base.AbstractVecOrTuple{<:Tensor})
+merge!(::Tenet.TensorNetwork, ::Tenet.TensorNetwork)
+delete!(::Tenet.TensorNetwork, ::Any)
+replace!
+selectdim
+slice!
+view(::Tenet.TensorNetwork)
+Base.copy(::Tenet.TensorNetwork)
+Base.rand(::Type{TensorNetwork}, n::Integer, regularity::Integer)
+```
+
+## Transformations
+
+```@docs
+transform
+transform!
+Tenet.HyperFlatten
+Tenet.HyperGroup
+Tenet.ContractSimplification
+Tenet.DiagonalReduction
+Tenet.AntiDiagonalGauging
+Tenet.Truncate
+Tenet.SplitSimplificationd
+```
diff --git a/docs/src/developer/cached-field.md b/docs/src/developer/cached-field.md
new file mode 100644
index 000000000..7d2c5237c
--- /dev/null
+++ b/docs/src/developer/cached-field.md
@@ -0,0 +1 @@
+# Cached field
diff --git a/docs/src/developer/hypergraph.md b/docs/src/developer/hypergraph.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/src/developer/keyword-dispatch.md b/docs/src/developer/keyword-dispatch.md
new file mode 100644
index 000000000..e69de29bb
diff --git a/docs/src/developer/type-hierarchy.md b/docs/src/developer/type-hierarchy.md
index 9c3584729..4839859f7 100644
--- a/docs/src/developer/type-hierarchy.md
+++ b/docs/src/developer/type-hierarchy.md
@@ -1,5 +1,9 @@
# Inheritance and Traits
+```@setup kroki
+using Kroki
+```
+
Julia (and in general, all modern languages like Rust or Go) implement Object Oriented Programming (OOP) in a rather restricted form compared to popular OOP languages like Java, C++ or Python.
In particular, they forbid _structural inheritance_; i.e. inheriting fields from parent superclass(es).
@@ -9,16 +13,28 @@ Julia design space on this topic is not completely clear. Julia has _abstract ty
As of the time of writing, the type hierarchy of Tenet looks like this:
-```mermaid
-graph TD
- id1(AbstractTensorNetwork) --> TensorNetwork
- id1(AbstractTensorNetwork) --> id2(AbstractQuantum)
- id2(AbstractQuantum) --> Quantum
- id2(AbstractQuantum) --> id3(Ansatz)
- id3(Ansatz) --> Product
- id3(Ansatz) --> Dense
- id3(Ansatz) --> Chain
+```@example kroki
+mermaid"""graph TD
+ id1(AbstractTensorNetwork)
+ id2(AbstractQuantum)
+ id3(AbstractAnsatz)
+ id4(AbstractMPO)
+ id5(AbstractMPS)
+ id1 -->|inherits| id2 -->|inherits| id3 -->|inherits| id4 -->|inherits| id5
+ id1 -->|inherits| TensorNetwork
+ id2 -->|inherits| Quantum
+ id3 -->|inherits| Ansatz
+ id3 -->|inherits| Product
+ id4 -->|inherits| MPO
+ id5 -->|inherits| MPS
+ Ansatz -.->|contains| Quantum -.->|contains| TensorNetwork
+ Product -.->|contains| Ansatz
+ MPO -.->|contains| Ansatz
+ MPS -.->|contains| Ansatz
style id1 stroke-dasharray: 5 5
style id2 stroke-dasharray: 5 5
style id3 stroke-dasharray: 5 5
+ style id4 stroke-dasharray: 5 5
+ style id5 stroke-dasharray: 5 5
+"""
```
diff --git a/docs/src/developer/unsafe-region.md b/docs/src/developer/unsafe-region.md
new file mode 100644
index 000000000..a3ce36ce1
--- /dev/null
+++ b/docs/src/developer/unsafe-region.md
@@ -0,0 +1,9 @@
+# Unsafe regions
+
+There are cases in which you may want to temporarily avoid index size checks on `push!` to a [`TensorNetwork`](@ref).
+
+```julia
+@unsafe_region tn begin
+ ...
+end
+```
diff --git a/docs/src/friends.md b/docs/src/friends.md
new file mode 100644
index 000000000..c1249f916
--- /dev/null
+++ b/docs/src/friends.md
@@ -0,0 +1,9 @@
+# Friends
+
+If `Tenet`'s design doesn't fit your case, ¡no problem!. There are other nice libraries in the wild, of which we recommend to take a look at:
+
+- [quimb](https://github.com/jcmgray/quimb) Flexible Tensor Network written in Python. Main source of inspiration for `Tenet`.
+- [tenpy](https://github.com/tenpy/tenpy) Tensor Network library written in Python with a strong focus on physics.
+- [ITensors.jl](https://github.com/ITensor/ITensors.jl) and [ITensorNetworks.jl](https://github.com/ITensors/ITensorNetworks.jl) Mature Tensor Network framework written in Julia.
+- [tensorkrowch](https://github.com/joserapa98/tensorkrowch) A new Tensor Network library built on top of PyTorch.
+- [SeeMPS](https://github.com/juanjosegarciaripoll/seemps)
diff --git a/docs/src/index.md b/docs/src/index.md
index 3d7960ed7..6ef4473a6 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,4 +1,48 @@
-# Tenet.jl
+```@raw html
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+ name: Tenet.jl
+ text: Hackable Tensor Networks
+ tagline:
+ actions:
+ - theme: brand
+ text: Manual
+ link: /manual
+ - theme: alt
+ text: API Reference 📚
+ link: /api/api
+ - theme: alt
+ text: View on GitHub
+ link: https://github.com/bsc-quantic/Tenet.jl
+ image:
+ src: /logo.svg
+ alt: Tenet.jl
+
+features:
+ - icon: 🚀
+ title: Fast & Device Agnostic
+ details: Its deep integration with Reactant.jl and carefully developed code, makes it go brrrr
+ link: /introduction
+
+ - icon: ∂
+ title: Built-In MLIR AD
+ details: Leverage Enzyme-Powered Automatic Differentiation to Differentiate MLIR Functions
+ link: /introduction
+
+ - icon: 🧩
+ title: Carefully crafted
+ details:
+ link: /introduction
+
+ - icon: 🫂
+ title: Compatible with friends
+ details:
+ link: /alternatives
+---
+```
!!! info "BSC-Quantic's Registry"
`Tenet` and some of its dependencies are located in our [own Julia registry](https://github.com/bsc-quantic/Registry).
@@ -9,20 +53,6 @@
pkg"registry add https://github.com/bsc-quantic/Registry"
```
-A Julia library for **_Ten_**sor **_Net_**works. `Tenet` can be executed both at local environments and on large supercomputers. Its goals are,
-
-- **Expressiveness** _Simple to use_ 👶
-- **Flexibility** _Extend it to your needs_ 🔧
-- **Performance** _Goes brr... fast_ 🏎️
-
-A video of its presentation at JuliaCon 2023 can be seen here:
-
-```@raw html
-
-
-
-```
-
## Features
- Optimized Tensor Network contraction, powered by [`EinExprs`](https://github.com/bsc-quantic/EinExprs.jl)
diff --git a/docs/src/manual/ansatz/index.md b/docs/src/manual/ansatz/index.md
new file mode 100644
index 000000000..d36fb337e
--- /dev/null
+++ b/docs/src/manual/ansatz/index.md
@@ -0,0 +1 @@
+# Ansatz
diff --git a/docs/src/ansatz/chain.md b/docs/src/manual/ansatz/mps.md
similarity index 97%
rename from docs/src/ansatz/chain.md
rename to docs/src/manual/ansatz/mps.md
index 37d32cfd4..91190139e 100644
--- a/docs/src/ansatz/chain.md
+++ b/docs/src/manual/ansatz/mps.md
@@ -51,8 +51,3 @@ fig # hide
```
In `Tenet`, the generic `MatrixProduct` ansatz implements this topology. Type variables are used to address their functionality (`State` or `Operator`) and their boundary conditions (`Open` or `Periodic`).
-
-```@docs
-MatrixProduct
-MatrixProduct(::Any)
-```
diff --git a/docs/src/ansatz/product.md b/docs/src/manual/ansatz/product.md
similarity index 100%
rename from docs/src/ansatz/product.md
rename to docs/src/manual/ansatz/product.md
diff --git a/docs/src/contraction.md b/docs/src/manual/contraction.md
similarity index 100%
rename from docs/src/contraction.md
rename to docs/src/manual/contraction.md
diff --git a/docs/src/manual/quantum.md b/docs/src/manual/quantum.md
new file mode 100644
index 000000000..4ecd0f012
--- /dev/null
+++ b/docs/src/manual/quantum.md
@@ -0,0 +1,5 @@
+# `Quantum` Tensor Networks
+
+## Queries
+
+## Connecting `Quantum` Tensor Networks
diff --git a/docs/src/manual/tensor-network.md b/docs/src/manual/tensor-network.md
new file mode 100644
index 000000000..11c57855b
--- /dev/null
+++ b/docs/src/manual/tensor-network.md
@@ -0,0 +1,25 @@
+# Tensor Networks
+
+Tensor Networks (TN) are a graphical notation for representing complex multi-linear functions. For example, the following equation
+
+```math
+\sum_{ijklmnop} A_{im} B_{ijp} C_{njk} D_{pkl} E_{mno} F_{ol}
+```
+
+can be represented visually as
+
+The graph's nodes represent tensors and edges represent tensor indices.
+
+In `Tenet`, these objects are represented by the [`TensorNetwork`](@ref) type.
+
+Information about a `TensorNetwork` can be queried with the following functions.
+
+## Query information
+
+## Modification
+
+### Add/Remove tensors
+
+### Replace existing elements
+
+## Slicing
diff --git a/docs/src/tensors.md b/docs/src/manual/tensors.md
similarity index 87%
rename from docs/src/tensors.md
rename to docs/src/manual/tensors.md
index 7d6b725dc..023522b9e 100644
--- a/docs/src/tensors.md
+++ b/docs/src/manual/tensors.md
@@ -4,6 +4,8 @@
using Tenet
```
+If you have reached here, you probably know wha a tensor is. Nevertheless, we are gonna give a brief remainder.
+
There are many jokes[^1] about how to define a _tensor_. The definition we are giving here might not be the most correct one, but it is good enough for our use case (don't kill me please, mathematicians).
A tensor $T$ of order[^2] $n$ is a multilinear[^3] application between $n$ vector spaces over a field $\mathcal{F}$.
@@ -23,10 +25,6 @@ T(\mathbf{v}^{(1)}, \dots, \mathbf{v}^{(n)}) = c \in \mathcal{F} \qquad\qquad \f
Tensor algebra is a higher-order generalization of linear algebra, where scalar numbers can be viewed as _order-0 tensors_, vectors as _order-1 tensors_, matrices as _order-2 tensors_, ...
-```@raw html
-
-Sketch of a Tensor Network
-
-```
-
-The graph's nodes represent tensors and edges represent tensor indices.
-
-In `Tenet`, these objects are represented by the [`TensorNetwork`](@ref) type.
-
-```@docs
-TensorNetwork
-```
-
-Information about a `TensorNetwork` can be queried with the following functions.
-
-## Query information
-
-```@docs
-inds(::Tenet.TensorNetwork)
-size(::Tenet.TensorNetwork)
-tensors(::Tenet.TensorNetwork)
-```
-
-## Modification
-
-### Add/Remove tensors
-
-```@docs
-push!(::Tenet.TensorNetwork, ::Tensor)
-append!(::Tenet.TensorNetwork, ::Base.AbstractVecOrTuple{<:Tensor})
-merge!(::Tenet.TensorNetwork, ::Tenet.TensorNetwork)
-pop!(::Tenet.TensorNetwork, ::Tensor)
-delete!(::Tenet.TensorNetwork, ::Any)
-```
-
-### Replace existing elements
-
-```@docs
-replace!
-```
-
-## Slicing
-
-```@docs
-selectdim
-slice!
-view(::Tenet.TensorNetwork)
-```
-
-## Miscelaneous
-
-```@docs
-Base.copy(::Tenet.TensorNetwork)
-Base.rand(::Type{TensorNetwork}, n::Integer, regularity::Integer)
-```
-
-```
-
Letters are used to identify each of the vector spaces the tensor relates to.
In computer science, you would intuitively think of tensors as "_n-dimensional arrays with named dimensions_".
@@ -46,28 +44,8 @@ Tᵢⱼₖ = Tensor(rand(3,5,2), (:i,:j,:k))
The _dimensionality_ or size of each index can be consulted using the `size` function.
-```@docs
-Base.size(::Tensor)
-```
-
```@repl tensor
size(Tᵢⱼₖ)
size(Tᵢⱼₖ, :j)
length(Tᵢⱼₖ)
```
-
-## Operations
-
-### Contraction
-
-```@docs
-Tenet.contract(::Tensor, ::Tensor)
-```
-
-### Factorizations
-
-```@docs
-LinearAlgebra.svd(::Tensor)
-LinearAlgebra.qr(::Tensor)
-LinearAlgebra.lu(::Tensor)
-```
diff --git a/docs/src/transformations.md b/docs/src/manual/transformations.md
similarity index 93%
rename from docs/src/transformations.md
rename to docs/src/manual/transformations.md
index a2b6e7e58..5a2c97885 100644
--- a/docs/src/transformations.md
+++ b/docs/src/manual/transformations.md
@@ -17,26 +17,12 @@ Our approach is based in [gray2021hyper](@cite), which can also be found in [qui
In Tenet, we provide a set of predefined transformations which you can apply to your `TensorNetwork` using both the `transform`/`transform!` functions.
-```@docs
-transform
-transform!
-```
-
## Available transformations
### Hyperindex converter
-```@docs
-Tenet.HyperFlatten
-Tenet.HyperGroup
-```
-
### Contraction simplification
-```@docs
-Tenet.ContractSimplification
-```
-
```@example plot
set_theme!(resolution=(800,200)) # hide
fig = Figure() #hide
@@ -60,10 +46,6 @@ fig #hide
### Diagonal reduction
-```@docs
-Tenet.DiagonalReduction
-```
-
```@example plot
set_theme!(resolution=(800,200)) # hide
fig = Figure() #hide
@@ -95,16 +77,8 @@ fig #hide
### Anti-diagonal reduction
-```@docs
-Tenet.AntiDiagonalGauging
-```
-
### Dimension truncation
-```@docs
-Tenet.Truncate
-```
-
```@example plot
set_theme!(resolution=(800,200)) # hide
fig = Figure() #hide
@@ -130,10 +104,6 @@ fig #hide
### Split simplification
-```@docs
-Tenet.SplitSimplification
-```
-
```@example plot
set_theme!(resolution=(800,200)) # hide
fig = Figure() #hide
diff --git a/docs/src/tensor-network.md b/docs/src/tensor-network.md
deleted file mode 100644
index b5b48ebe8..000000000
--- a/docs/src/tensor-network.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Tensor Networks
-
-Tensor Networks (TN) are a graphical notation for representing complex multi-linear functions. For example, the following equation
-
-```math
-\sum_{ijklmnop} A_{im} B_{ijp} C_{njk} D_{pkl} E_{mno} F_{ol}
-```
-
-can be represented visually as
-
-```@raw html
-