docs: setup user manual

2026-06-24 15:53:52 +02:00
parent f7c43837b5
commit 93ddb28802
3 changed files with 240 additions and 0 deletions
--- a/assets/icon.svg
+++ b/assets/icon.svg
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="128"
+   height="128"
+   viewBox="0 0 128 128"
+   version="1.1"
+   id="svg1"
+   inkscape:export-filename="logo.png"
+   inkscape:export-xdpi="96"
+   inkscape:export-ydpi="96"
+   inkscape:version="1.4.4 (1:1.4.4+202605061436+dcaf3e7d9e)"
+   sodipodi:docname="logo.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     showgrid="true"
+     inkscape:zoom="1.9332778"
+     inkscape:cx="-8.2760999"
+     inkscape:cy="112.2446"
+     inkscape:window-width="2584"
+     inkscape:window-height="1028"
+     inkscape:window-x="0"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1">
+    <inkscape:grid
+       id="grid1"
+       units="px"
+       originx="0"
+       originy="0"
+       spacingx="4"
+       spacingy="4"
+       empcolor="#0099e5"
+       empopacity="0.30196078"
+       color="#0099e5"
+       opacity="0.14901961"
+       empspacing="4"
+       enabled="true"
+       visible="true" />
+  </sodipodi:namedview>
+  <defs
+     id="defs1">
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4689"
+       id="linearGradient1478"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.562541,0,0,0.567972,-9.399749,-5.305317)"
+       x1="26.648937"
+       y1="20.603781"
+       x2="135.66525"
+       y2="114.39767" />
+    <linearGradient
+       id="linearGradient4689">
+      <stop
+         style="stop-color:#e1be1e;stop-opacity:1;"
+         offset="0"
+         id="stop4691" />
+      <stop
+         style="stop-color:#ffeb82;stop-opacity:1;"
+         offset="1"
+         id="stop4693" />
+    </linearGradient>
+    <linearGradient
+       inkscape:collect="always"
+       xlink:href="#linearGradient4671"
+       id="linearGradient1475"
+       gradientUnits="userSpaceOnUse"
+       gradientTransform="matrix(0.562541,0,0,0.567972,-9.399749,-5.305317)"
+       x1="150.96111"
+       y1="192.35176"
+       x2="112.03144"
+       y2="137.27299" />
+    <linearGradient
+       id="linearGradient4671">
+      <stop
+         style="stop-color:#ffdc21;stop-opacity:1;"
+         offset="0"
+         id="stop4673" />
+      <stop
+         style="stop-color:#ffeb82;stop-opacity:1;"
+         offset="1"
+         id="stop4675" />
+    </linearGradient>
+  </defs>
+  <g
+     inkscape:label="Calque 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <g
+       id="g1"
+       transform="translate(2.911719,3.414527)">
+      <path
+         style="fill:url(#linearGradient1478);fill-opacity:1"
+         d="m 60.510156,6.3979729 c -4.583653,0.021298 -8.960939,0.4122177 -12.8125,1.09375 C 36.35144,9.4962267 34.291407,13.691825 34.291406,21.429223 v 10.21875 h 26.8125 v 3.40625 h -26.8125 -10.0625 c -7.792459,0 -14.6157592,4.683717 -16.7500002,13.59375 -2.46182,10.212966 -2.5710151,16.586023 0,27.25 1.9059283,7.937852 6.4575432,13.593748 14.2500002,13.59375 h 9.21875 v -12.25 c 0,-8.849902 7.657144,-16.656248 16.75,-16.65625 h 26.78125 c 7.454951,0 13.406253,-6.138164 13.40625,-13.625 v -25.53125 c 0,-7.266339 -6.12998,-12.7247775 -13.40625,-13.9375001 -4.605987,-0.7667253 -9.385097,-1.1150483 -13.96875,-1.09375 z m -14.5,8.2187501 c 2.769547,0 5.03125,2.298646 5.03125,5.125 -2e-6,2.816336 -2.261703,5.09375 -5.03125,5.09375 -2.779476,-1e-6 -5.03125,-2.277415 -5.03125,-5.09375 -1e-6,-2.826353 2.251774,-5.125 5.03125,-5.125 z"
+         id="path1948" />
+      <path
+         style="fill:url(#linearGradient1475);fill-opacity:1"
+         d="m 91.228906,35.054223 v 11.90625 c 0,9.230755 -7.825895,16.999999 -16.75,17 h -26.78125 c -7.335833,0 -13.406249,6.278483 -13.40625,13.625 v 25.531247 c 0,7.26634 6.318588,11.54032 13.40625,13.625 8.487331,2.49561 16.626237,2.94663 26.78125,0 6.750155,-1.95439 13.406253,-5.88761 13.40625,-13.625 V 92.897973 h -26.78125 v -3.40625 h 26.78125 13.406254 c 7.79246,0 10.69625,-5.435408 13.40624,-13.59375 2.79933,-8.398886 2.68022,-16.475776 0,-27.25 -1.92578,-7.757441 -5.60387,-13.59375 -13.40624,-13.59375 z m -15.0625,64.65625 c 2.779478,3e-6 5.03125,2.277417 5.03125,5.093747 -2e-6,2.82635 -2.251775,5.125 -5.03125,5.125 -2.76955,0 -5.03125,-2.29865 -5.03125,-5.125 2e-6,-2.81633 2.261697,-5.093747 5.03125,-5.093747 z"
+         id="path1950" />
+    </g>
+  </g>
+</svg>
--- a/docs/manual.typ
+++ b/docs/manual.typ
@@ -0,0 +1,27 @@
+#import "template.typ": TODO, project
+
+#let midas-version = toml("../pyproject.toml").project.version
+#let head-ref = read("../.git/HEAD").split(":").at(1).trim()
+#let commit-hash = read("../.git/" + head-ref).slice(0, 8)
+
+#show: project.with(
+  title: [Midas User Manual],
+  author: "Louis Heredero",
+  version: midas-version,
+  hash: commit-hash,
+  icon-path: path("../assets/icon.svg"),
+)
+
+= Introduction
+
+#TODO
+
+= Installation
+
+#TODO
+
+= Quick Start
+
+This chapter will give you the keys to quickly start using Midas in your project.
+
+#TODO
--- a/docs/template.typ
+++ b/docs/template.typ
@@ -0,0 +1,96 @@
+#import "@preview/modpattern:0.2.0": modpattern
+
+#let TODO = block(
+  width: 6em,
+  height: 3em,
+  stroke: red,
+  fill: modpattern(
+    size: (10pt, 10pt),
+    line(
+      start: (0%, 0%),
+      end: (100%, 100%),
+      stroke: gray.transparentize(60%) + 2pt,
+    ),
+  ),
+  align(
+    center + horizon,
+    text(fill: red, size: 1.5em)[*TODO*],
+  ),
+)
+
+#let _render-header(version, hash) = {
+  let last-heading = query(heading.where(level: 1).before(here())).last(default: none)
+  let next-heading = query(heading.where(level: 1).after(here())).first(default: none)
+
+  let current-heading = if next-heading != none and next-heading.location().page() == here().page() {
+    next-heading
+  } else if last-heading != none {
+    last-heading
+  } else { none }
+
+  let chapter = if current-heading != none {
+    let body = current-heading.body
+    if current-heading.numbering != none {
+      let num = counter(heading).display(current-heading.numbering, at: current-heading.location())
+      body = [#num #body]
+    }
+    body
+  } else []
+
+  grid(
+    columns: (1fr, auto, 1fr),
+    align: (left, center, right),
+    document.title, [v#version - #hash], chapter,
+  )
+}
+
+#let project(
+  title: none,
+  author: none,
+  version: "0.0.1",
+  hash: "abcdefgh",
+  icon-path: none,
+  doc,
+) = {
+  assert(title != none, message: "Please provide a title")
+
+  set document(
+    title: title,
+    author: author,
+  )
+  set text(
+    font: "Source Sans 3",
+  )
+
+  show std.title: set text(size: 1.5em)
+
+  show heading.where(level: 1): it => {
+    pagebreak()
+    it
+  }
+
+  set page(
+    header: context if counter(page).get().first() != 1 { _render-header(version, hash) },
+    footer: context if counter(page).get().first() != 1 and page.numbering != none {
+      align(center, counter(page).display(page.numbering, both: true))
+    },
+    numbering: "1 / 1",
+  )
+
+  // Title page
+  align(center)[
+    #std.title()
+
+    v#version - #hash
+
+    #if icon-path != none {
+      v(1cm)
+      image(icon-path)
+    }
+  ]
+
+  outline()
+  show heading.where(level: 1): set heading(numbering: "I.")
+
+  doc
+}