Merge pull request #1 from owid/docs/enhance

migrate docs to mkdocs

.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.10"
+  commands:
+    - git submodule init
+    - git submodule update
+    - pip install -r requirements.txt
+    - mkdocs build
+    - mkdir -p _readthedocs
+    - cp -r site/ _readthedocs/html/
+
+submodules:
+  include: all

docs/covid.md

@@ -0,0 +1,10 @@
+---
+template: redirect.html
+
+location: https://docs.owid.io/projects/covid
+
+title: covid-19-data
+icon: octicons/link-external-24
+---
+
+<!-- Comment to trigger proper build -->

docs/etl.md

@@ -0,0 +1,10 @@
+---
+template: redirect.html
+
+location: https://docs.owid.io/projects/etl
+
+title: etl
+icon: octicons/link-external-24
+---
+
+<!-- Comment to trigger proper build -->

docs/index.md

@@ -0,0 +1,38 @@
+---
+hide:
+ - navigation
+ - toc
+---
+<!-- <style>
+  .md-typeset h1,
+  .md-content__button {
+    display: none;
+  }
+</style> -->
+
+# Welcome to our technical documentation!
+
+Here you can find the links to our various projects and their respective documentation. To learn more about our projects, you can refer to our [GitHub page](https://github.com/owid).
+
+
+<div class="grid cards" markdown>
+
+-   __[:fontawesome-solid-database: &nbsp; etl :octicons-link-external-16:](https://docs.owid.io/projects/etl)__
+
+    ---
+
+    Learn more about our data workflow.
+
+-   __[:material-chart-line: &nbsp; owid-grapher :octicons-link-external-16:](https://owid-grapher.readthedocs.io/en/docs-revamp-2023/)__
+
+    ---
+
+    Learn more about our visualisation and website infrastructure.
+
+-   __[:material-virus: &nbsp; covid-19-data :octicons-link-external-16:](https://docs.owid.io/projects/covid)__
+
+    ---
+
+    Learn more about our COVID-19 data.
+
+</div>

docs/owid-grapher.md

@@ -0,0 +1,10 @@
+---
+template: redirect.html
+
+location: https://owid-grapher.readthedocs.io/en/docs-revamp-2023/
+
+title: owid-grapher
+icon: octicons/link-external-24
+---
+
+<!-- Comment to trigger proper build -->

mkdocs.yml

@@ -0,0 +1,108 @@
+# Project information
+site_name: OWID documentation
+site_url: https://docs.owid.io/
+site_author: Our World in Data
+site_description: >-
+  Tecnical documentation at Our World in Data.
+
+# Repository
+# repo_name: owid/etl
+# repo_url: https://github.com/owid/
+
+
+# Copyright
+copyright: Copyright © 2024 Our World in Data
+
+
+theme:
+  features:
+    # - navigation.tabs
+    # # Code blocks can automatically render a button on the right side to allow the user to copy a code block's contents to the clipboard. ref: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-copy-button
+    # - content.code.copy
+    # # Code annotations offer a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block and inline comments in the language of the code block. ref: https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations
+    # - content.code.annotate
+    # - content.tooltips
+    # # When expansion is enabled, the left sidebar will expand all collapsible subsections by default, so the user doesn't have to open subsections manually. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-expansion
+    # - navigation.expand
+    # # When section index pages are enabled, documents can be directly attached to sections, which is particularly useful for providing overview pages. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-pruning
+    # - navigation.indexes
+    # # When instant loading is enabled, clicks on all internal links will be intercepted and dispatched via XHR without fully reloading the page. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading
+    # - navigation.instant
+    # # In order to provide a better user experience on slow connections when using instant navigation, a progress indicator can be enabled. It will be shown at the top of the page and will be hidden once the page has fully loaded.
+    # - navigation.instant.progress
+    # # When pruning is enabled, only the visible navigation items are included in the rendered HTML, reducing the size of the built site by 33% or more. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-pruning
+    # # - navigation.prune
+    # # When sections are enabled, top-level sections are rendered as groups in the sidebar for viewports above 1220px, but remain as-is on mobile. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-sections
+    # - navigation.sections
+    # # When tabs are enabled, top-level sections are rendered in a menu layer below the header for viewports above 1220px, but remain as-is on mobile. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs
+    # # When sticky tabs are enabled, navigation tabs will lock below the header and always remain visible when scrolling down.
+    # # - navigation.tabs.sticky
+    # # A back-to-top button can be shown when the user, after scrolling down, starts to scroll up again. It's rendered centered and just below the header. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button
+    # # - navigation.top
+    # # When anchor tracking is enabled, the URL in the address bar is automatically updated with the active anchor as highlighted in the table of contents. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking
+    # # - navigation.tracking
+    # # When search sharing is activated, a  share button is rendered next to the reset button, which allows to deep link to the current search query and result. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-sharing
+    # # - search.share
+    # # When search suggestions are enabled, the search will display the likeliest completion for the last word which can be accepted with the Right key. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-suggestions
+    # # - search.suggest
+    # # When search highlighting is enabled and a user clicks on a search result, Material for MkDocs will highlight all occurrences after following the link. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#search-highlighting
+    # # - search.highlight
+    # # When anchor following for the table of contents is enabled, the sidebar is automatically scrolled so that the active anchor is always visible. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#table-of-contents
+    # # - toc.follow
+    # # When navigation integration for the table of contents is enabled, it is always rendered as part of the navigation sidebar on the left. ref: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#table-of-contents
+    # # - toc.integrate
+    # # - navigation.expand
+    # # - navigation.sections
+    # # - toc.follow
+  name: material
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: pink
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: "amber"
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  font:
+    text: Helvetica Neue
+  favicon: assets/favicon.png
+  logo: "assets/site-logo.svg"
+
+markdown_extensions: 
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+extra:
+  homepage: https://docs.owid.io/
+  generator: true
+  status:
+    new: Recently added
+    deprecated: Deprecated
+  social:
+    # icons available listed: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons/fontawesome
+    - icon: fontawesome/brands/github
+      link: https://github.com/ourworldindata
+    - icon: fontawesome/solid/globe
+      link: https://ourworldindata.org
+    - icon: fontawesome/brands/instagram
+      link: https://instagram.com/ourworldindata
+    - icon: fontawesome/brands/x-twitter
+      link: https://twitter.com/ourworldindata
+
+nav:
+  - OWID documentation: "index.md"
+  - etl: "etl.md"
+  - owid-grapher: "owid-grapher.md"
+  - covid: "covid.md"