Docusaurus

.github/workflows/deploy-doc.yml

@@ -0,0 +1,86 @@
+name: deploy-doc
+
+on:
+  push:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: doc/package-lock.json
+
+      - name: Install Docusaurus Dependencies
+        working-directory: ./doc
+        run: npm ci
+
+      - name: Setup OCaml
+        uses: ocaml/setup-ocaml@v3
+        with:
+          ocaml-compiler: "5.2.x"
+          opam-repositories: |
+            default: https://github.com/ocaml/opam-repository.git
+            mbarbin: https://github.com/mbarbin/opam-repository.git
+#           janestreet-bleeding: https://github.com/janestreet/opam-repository.git
+#           janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
+
+      - name: Install OCaml Dependencies
+        run: opam install . --deps-only --with-doc
+
+      - name: Build Odoc Pages
+        run: opam exec -- dune build @doc
+
+      - name: Copy Odoc Pages to Docusaurus Static Directory
+        run: |
+          rm -rf doc/static/odoc
+          cp -R _build/default/_doc/_html doc/static/odoc
+
+      - name: Build Website
+        working-directory: ./doc
+        run: npm run build
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./doc
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-deploy-doc.yml

@@ -0,0 +1,57 @@
+name: test-deploy-doc
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: doc/package-lock.json
+
+      - name: Install Docusaurus Dependencies
+        working-directory: ./doc
+        run: npm ci
+
+      - name: Setup OCaml
+        uses: ocaml/setup-ocaml@v3
+        with:
+          ocaml-compiler: "5.2.x"
+          opam-repositories: |
+            default: https://github.com/ocaml/opam-repository.git
+            mbarbin: https://github.com/mbarbin/opam-repository.git
+#           janestreet-bleeding: https://github.com/janestreet/opam-repository.git
+#           janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
+
+      - name: Install OCaml Dependencies
+        run: opam install . --deps-only --with-doc
+
+      - name: Build Odoc Pages
+        run: opam exec -- dune build @doc
+
+      - name: Copy Odoc Pages to Docusaurus Static Directory
+        run: |
+          rm -rf doc/static/odoc
+          cp -R _build/default/_doc/_html doc/static/odoc
+
+      - name: Build Website
+        working-directory: ./doc
+        run: npm run build

doc/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

doc/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

doc/blog/2024-07-24-hello/index.md

@@ -0,0 +1,8 @@
+---
+slug: hello
+title: Hello
+authors: [mbarbin]
+tags: [hello]
+---
+
+Hello! I've just launched a blog section within the ocaml-vcs documentation, powered by Docusaurus. This new space is designed to keep you updated with all things related to ocaml-vcs. Stay tuned for more updates and insights. Happy reading!

doc/blog/authors.yml

@@ -0,0 +1,5 @@
+mbarbin:
+  name: Mathieu Barbin
+  title: Maintainer of ocaml-vcs
+  url: https://github.com/mbarbin
+  image_url: https://github.com/mbarbin.png

doc/blog/tags.yml

@@ -0,0 +1,4 @@
+hello:
+  label: Hello
+  permalink: /hello
+  description: Hello tag description

doc/docs/odoc/odoc.md

@@ -0,0 +1,3 @@
+# OCaml Packages Documentation
+
+You can view the published odoc pages here: [https://mbarbin.github.io/vcs/odoc/](https://mbarbin.github.io/vcs/odoc/).

doc/docs/tests/dune

@@ -0,0 +1,5 @@
+(mdx
+ (deps
+  (package vcs)
+  (package vcs-command))
+ (preludes prelude.txt))

doc/docs/tests/exploratory_tests.md

@@ -0,0 +1,64 @@
+# Exploratory tests
+
+The `vcs-command` package introduces an executable, `ocaml-vcs`, designed to bring the core functionalities of ocaml-vcs directly to your command line.
+
+It's a practical tool for conducting exploratory testing within your repositories, and reproducing bugs or issues externally, for a smoother debugging process. As a live code sample, it also demonstrates the use of the library.
+
+Whether you're testing new features, diagnosing problems, or seeking to understand the library's application, `ocaml-vcs` can be a useful resource.
+
+Below is a quick overview of the commands available in `ocaml-vcs`:
+
+```bash
+$ ocaml-vcs help -expand-dots -flags -recursive
+call a command from the vcs interface
+
+  ocaml-vcs SUBCOMMAND
+
+This is an executable to test the Version Control System (vcs) library.
+
+We expect a 1:1 mapping between the function exposed in the [Vcs.S] and the
+sub commands exposed here, plus additional functionality in [more-tests].
+
+=== subcommands and flags ===
+
+  add                        . add a file to the index
+  commit                     . commit a file
+  commit --message MSG, -m   . commit message
+  commit [--quiet], -q       . suppress output on success
+  current-branch             . current branch
+  current-revision           . revision of HEAD
+  git                        . run the git cli
+  git [--]                   . pass the remaining args to git
+  init                       . initialize a new repository
+  init [--quiet], -q         . suppress output on success
+  load-file                  . print a file from the filesystem (aka cat)
+  log                        . show the log of current repo
+  ls-files                   . list file
+  ls-files [--below PATH]    . only below path
+  more-tests                 . more tests combining vcs functions
+  more-tests branch-revision . revision of a branch
+  name-status                . show a summary of the diff between 2 revs
+  num-status                 . show a summary of the number of lines of diff
+                               between 2 revs
+  refs                       . show the refs of current repo
+  rename-current-branch      . move/rename a branch to a new name
+  save-file                  . save stdin to a file from the filesystem (aka
+                               tee)
+  set-user-config            . set the user config
+  set-user-config --user.email EMAIL
+                             . user email
+  set-user-config --user.name USER
+                             . user name
+  show-file-at-rev           . show the contents of file at a given revision
+  show-file-at-rev --rev REV, -r
+                             . revision
+  tree                       . compute tree of current repo
+  version                    . print version information
+  version [-build-info]      . print build info for this build
+  version [-version]         . print the version of this build
+  help                       . explain a given subcommand (perhaps recursively)
+  help [-expand-dots]        . expand subcommands in recursive help
+  help [-flags]              . show flags as well in recursive help
+  help [-recursive]          . show subcommands of subcommands, etc.
+
+```

doc/docs/tests/prelude.txt

@@ -0,0 +1 @@
+#require "vcs";;

doc/docusaurus.config.ts

@@ -0,0 +1,128 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'ocaml-vcs',
+  tagline: 'A versatile OCaml library for Git interaction',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://mbarbin.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/vcs/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'mbarbin', // Usually your GitHub org/user name.
+  projectName: 'vcs', // Usually your repo name.
+
+  trailingSlash: true,
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl: 'https://github.com/mbarbin/vcs/tree/main/doc/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl: 'https://github.com/mbarbin/vcs/tree/main/doc/',
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    // Replace with your project's social card
+    image: 'img/ocaml-vcs.png',
+    navbar: {
+      hideOnScroll: true,
+      title: 'ocaml-vcs',
+      logo: {
+        alt: 'Site Logo',
+        src: 'img/ocaml-vcs.png',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'odocSidebar',
+          position: 'left',
+          label: 'OCaml Packages',
+        },
+        {
+          type: 'docSidebar',
+          sidebarId: 'testsSidebar',
+          position: 'left',
+          label: 'Tests',
+        },
+        { to: '/blog/', label: 'Blog', position: 'left' },
+        {
+          href: 'https://github.com/mbarbin/vcs',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {
+              label: 'OCaml Packages',
+              to: '/docs/odoc/',
+            },
+            {
+              label: 'Tests',
+              to: '/docs/tests/exploratory_tests/',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'Blog',
+              to: '/blog',
+            },
+            {
+              label: 'GitHub',
+              href: 'https://github.com/mbarbin/vcs',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} Mathieu Barbin. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['bash', 'diff', 'json', 'ocaml'],
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;