{"id":18841920,"url":"https://github.com/diskuv/odoc-sandbox","last_synced_at":"2026-03-19T06:40:49.406Z","repository":{"id":114369948,"uuid":"551766012","full_name":"diskuv/odoc-sandbox","owner":"diskuv","description":"A home for experiments on odoc, the OCaml documentation tool","archived":false,"fork":false,"pushed_at":"2023-04-01T18:35:20.000Z","size":186,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T05:45:56.972Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://diskuv.github.io/odoc-sandbox/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/diskuv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-15T03:41:54.000Z","updated_at":"2022-11-28T19:10:35.000Z","dependencies_parsed_at":"2023-07-01T19:08:16.173Z","dependency_job_id":null,"html_url":"https://github.com/diskuv/odoc-sandbox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/diskuv/odoc-sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fodoc-sandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fodoc-sandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fodoc-sandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fodoc-sandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/diskuv","download_url":"https://codeload.github.com/diskuv/odoc-sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/diskuv%2Fodoc-sandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29472880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T06:58:05.414Z","status":"ssl_error","status_checked_at":"2026-02-15T06:58:05.085Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T02:53:02.826Z","updated_at":"2026-02-15T07:32:27.596Z","avatar_url":"https://github.com/diskuv.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# odoc-sandbox\n\nThis project is a home (\"sandbox\") for experiments on [odoc](https://github.com/ocaml/odoc).\n\nThe experiment results are rendered at [https://diskuv.github.io/odoc-sandbox/](https://diskuv.github.io/odoc-sandbox/).\n\n## Usage\n\nTo modify the sandbox you will need to:\n\n1. Check out the source code locally on your computer\n2. Install the system requirements for your operating system:\n\n   | System Requirements              |\n   | -------------------------------- |\n   | [macOS](#requirements-macos)     |\n   | [Windows](#requirements-windows) |\n\n   \u003e Linux users: Please adapt the [macOS](#requirements-macos) requirements and submit a PR to update\n   \u003e  the install instructions!\n\nThen you can use:\n\n| Command                                                                              | What                                                |\n| ------------------------------------------------------------------------------------ | --------------------------------------------------- |\n| `conda run -n odoc-sandbox make`                                                     | setup an Opam switch and run the experiments        |\n| `conda run -n odoc-sandbox make ide`                                                 | setup an Opam switch with OCaml LSP and ocamlformat |\n| `conda run -n odoc-sandbox --live-stream make server`                                | see the resulting HTML at http://localhost:8000     |\n| `conda run -n odoc-sandbox --live-stream dune build @runtest --auto-promote --watch` | autorun the experiments                             |\n\nYou will find it useful to do the `... make server` and the `... dune build ... --watch` commands in parallel; you can tweak\nan experiment and see the result by refreshing the page.\n\n## Directory Structure\n\n| Directory             | Purpose                                                  |\n| --------------------- | -------------------------------------------------------- |\n| `content/`            | Source `.mli` and `.mld` content                         |\n| `exp/NNN-name/`       | The experiments, numbered from simplest to most advanced |\n| `exp/res/odoc-theme/` | CSS and JS provided by odoc                              |\n| `exp/res/index/`      | CSS and JS needed for hand-crafted index.html            |\n\nEach experiment copies what it needs from `content/`.\n\n## Requirements: macOS\n\n| macOS Packages | Installing                         |\n| -------------- | ---------------------------------- |\n| pandoc         | See [macOS: python](#macos-python) |\n| sphinx         | See [macOS: sphinx](#macos-sphinx) |\n\n### macOS: python\n\nFIRST, install the Python package manager \"miniconda\" (skip this step if you have already installed miniconda or anaconda):\n\n```console\n$ if ! command -v conda; then\n    brew install miniconda\n  fi\n\n...\n==\u003e Linking Binary 'conda' to '/opt/homebrew/bin/conda'\n🍺  miniconda was successfully installed!\n```\n\nSECOND (optional!) if you like conda in your PATH you can do:\n\n```console\n$ conda init \"$(basename \"${SHELL}\")\"\n\n...\n==\u003e For changes to take effect, close and re-open your current shell. \u003c==\n```\n\nTHIRD, close and re-open your current shell (ex. Terminal)\n\nFOURTH, run the following:\n\n```console\n$ conda update -n base -c defaults conda\n$ if ! conda list -q -n odoc-sandbox \u0026\u003e/dev/null; then\n    conda env create -f environment.yml\n  else\n    conda env update -f environment.yml\n  fi\n```\n\n*The above command can be run repeatedly; you can use it for upgrading Python dependencies.*\n\n### macOS: sphinx\n\nWe avoid the version from `brew install sphinx` since it says:\n\n```\nWarning: sphinx has been deprecated because it is using unsupported v2 and source for v3 is not publicly available!\n```\n\nJust follow the [Python installation instructions](#macos-python)!\n\n## Requirements: Windows\n\n| Windows Packages | Installing                         |\n| ---------------- | ---------------------------------- |\n| make             | See [Win32: make](#win32-make)     |\n| pandoc           | See [Win32: python](#win32-python) |\n| sphinx           | See [Win32: python](#win32-python) |\n\n### Win32: make\n\n`make` is available on Windows with Cygwin or MSYS2.\n\n\u003e If you installed Windows DKML, you can use `with-dkml make` to replace `make`. For example,\n\u003e run:\n\u003e ```bash\n\u003e conda run -n odoc-sandbox with-dkml make\n\u003e ```\n\u003e instead of\n\u003e ```bash\n\u003e conda run -n odoc-sandbox make\n\u003e ```\n\n### Win32: python\n\nFIRST download and install from https://docs.conda.io/en/latest/miniconda.html\n\nSECOND, in **PowerShell** do the following:\n\n```powershell\nPS\u003e \u0026conda update -n base -c defaults conda\nPS\u003e \u0026conda list -q -n odoc-sandbox | Out-Null\n    if ($LASTEXITCODE) {\n      \u0026conda env create -f environment.yml\n    } else {\n      \u0026conda env update -f environment.yml\n    }\n```\n\n## Recommendations\n\n### direnv\n\nIf you use direnv (Unix only), the `.envrc` below will help you avoid typing in\n`conda run -n odoc-sandbox` before every command.\n\nFIRST, do a `make` to ensure you have an opam switch.\n\nSECOND, write the following `.envrc` in the project directory (same directory as this README):\n\n```shell\n#!/bin/sh\nexport OPAMROOT=\"$HOME/.config/opam\"\n#   shellcheck disable=SC2046\neval $(conda run -n odoc-sandbox opam env --set-switch)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiskuv%2Fodoc-sandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiskuv%2Fodoc-sandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiskuv%2Fodoc-sandbox/lists"}