new docs, complete

.github/workflows/Documenter.yml

@@ -0,0 +1,33 @@
+name: Documenter
+on:
+  push:
+    branches: [main]
+    tags: [v*]
+  pull_request:
+    branches: [main]
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@v1
+      - uses: julia-actions/cache@v1
+        with:
+          cache-registries: "true"
+      - name: Install documentation dependencies
+        run: julia --project=docs -e 'using Pkg; pkg"dev ."; Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          JULIA_DEBUG: "Documenter"
+          DATADEPS_ALWAYS_ACCEPT: true
+        run: |
+          julia --code-coverage=user --project=docs/ --color=yes docs/make.jl

.github/workflows/ci.yml

@@ -41,14 +41,3 @@ jobs:
       - uses: codecov/codecov-action@v1
         with:
           file: lcov.info
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/cache@v1
-      - uses: julia-actions/julia-buildpkg@latest
-      - uses: julia-actions/julia-docdeploy@latest
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -1,8 +1,19 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
-docs/build/
-docs/site/
 Manifest.toml
 .DS_Store
 .vscode
+
+/Manifest.toml
+/.vscode/
+tmp
+generated
+build
+
+docs/docs
+docs/site
+docs/build
+docs/var
+deps/build.jl
+Manifest.toml

docs/Project.toml

@@ -3,8 +3,10 @@ CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
 Chain = "8be319e6-bccf-4806-a6f7-6fae938471bc"
 DataFrameMacros = "75880514-38bc-4a95-a458-c2aea5a3a702"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DataFramesMeta = "1313f7d8-7da2-5740-9ea0-a2ca25f37964"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433"
 Missings = "e1d29d7a-bbdc-5cf2-9ac0-f12de2c33e28"
 Query = "1a8c2f83-1ff3-5112-b086-8aa67b057ba1"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"

docs/make.jl

@@ -1,58 +1,32 @@
-using Documenter
+using Documenter, DocumenterMarkdown
 using DataFrames
 using CategoricalArrays
 
-DocMeta.setdocmeta!(DataFrames, :DocTestSetup, :(using DataFrames); recursive=true)
-
 # Build documentation.
 # ====================
-
 makedocs(
-    # options
     modules = [DataFrames],
-    doctest = true,
-    clean = false,
-    sitename = "DataFrames.jl",
-    format = Documenter.HTML(
-        canonical = "https://juliadata.github.io/DataFrames.jl/stable/",
-        assets = ["assets/favicon.ico"],
-        edit_link = "main"
-    ),
-    pages = Any[
-        "Introduction" => "index.md",
-        "First Steps with DataFrames.jl" => "man/basics.md",
-        "User Guide" => Any[
-            "Getting Started" => "man/getting_started.md",
-            "Working with DataFrames" => "man/working_with_dataframes.md",
-            "Importing and Exporting Data (I/O)" => "man/importing_and_exporting.md",
-            "Joins" => "man/joins.md",
-            "Split-apply-combine" => "man/split_apply_combine.md",
-            "Reshaping" => "man/reshaping_and_pivoting.md",
-            "Sorting" => "man/sorting.md",
-            "Categorical Data" => "man/categorical.md",
-            "Missing Data" => "man/missing.md",
-            "Data manipulation frameworks" => "man/querying_frameworks.md",
-            "Comparison with Python/R/Stata" => "man/comparisons.md"
-        ],
-        "API" => Any[
-            "Types" => "lib/types.md",
-            "Functions" => "lib/functions.md",
-            "Indexing" => "lib/indexing.md",
-            "Metadata" => "lib/metadata.md",
-            hide("Internals" => "lib/internals.md"),
-        ]
-    ],
-    strict = true
+    clean=true,
+    doctest=false,
+    sitename="DataFrames.jl",
+    authors="Bogumił Kamiński et al.",
+    strict=[
+        :doctest,
+        :linkcheck,
+        :parse_error,
+        :example_block,
+        # Other available options are
+        # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block,
+        # :footnote, :meta_block, :missing_docs, :setup_block
+    ], checkdocs=:all, format=Markdown(), draft=false,
+    build=joinpath(@__DIR__, "docs")
 )
 
 # Deploy built documentation from Travis.
 # =======================================
 
-deploydocs(
-    # options
-    repo = "github.com/JuliaData/DataFrames.jl.git",
-    target = "build",
-    deps = nothing,
-    make = nothing,
-    devbranch = "main"
-)
+deploydocs(; repo="github.com/JuliaData/DataFrames.jl.git", push_preview=true,
+    deps=Deps.pip("mkdocs", "pygments", "python-markdown-math", "mkdocs-material",
+        "pymdown-extensions", "mkdocstrings", "mknotebooks",
+        "pytkdocs_tweaks", "mkdocs_include_exclude_files", "jinja2", "mike"),
+    make=() -> run(`mkdocs build`), target="site", devbranch="main")

docs/mkdocs.yml

@@ -0,0 +1,143 @@
+theme:
+  name: material
+  logo: assets/logo.png
+  features:
+    - content.code.copy
+    # - announce.dismiss
+    - content.code.annotate
+    # - content.tabs.link
+    #- content.tooltips
+    # - header.autohide
+    - navigation.expand
+    #- navigation.indexes
+    # - navigation.instant
+    - navigation.prune
+    #- navigation.sections
+    #- navigation.tabs
+    # - navigation.tabs.sticky
+    - navigation.top
+    - navigation.footer
+    #- navigation.tracking
+    - search.highlight
+    - search.share
+    - search.suggest
+    - toc.follow
+    #- toc.integrate # Table of contents is integrated on the left; does not appear separately on the right.
+    - header.autohide # header disappears as you scroll
+  palette:
+
+    # Light mode 
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: red
+      accent: green
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+
+    # Dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue grey
+      accent: deep orange
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode
+  font:
+    text: Lato
+  icon:
+    repo: fontawesome/brands/github # GitHub logo in top right
+    #logo: "material/gridoff" # Equinox logo in top left
+  #  favicon: "_static/icon_transparent.svg"
+#  custom_dir: "_overrides" # Overriding part of the HTML
+
+  # These additions are my own custom ones, having overridden a partial.
+  #twitter_name: ""
+  #twitter_url: ""
+site_name: DataFrames.jl
+site_description: DataFrames.jl
+site_author: Lazaro Alonso & Bogumił Kamiński
+site_url: ""
+
+repo_url: https://github.com/JuliaData/DataFrames.jl
+repo_name: DataFrames.jl
+edit_uri: "" # No edit button, as some of our pages are in /docs and some in /examples via symlink, so it's impossible for them all to be accurate
+
+strict: true # Don't allow warnings during the build process
+extra_javascript:
+  # The below three make MathJax work, see https://squidfunk.github.io/mkdocs-material/reference/mathjax/
+  - _static/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/JuliaData/DataFrames.jl
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/BogumilKaminski
+
+extra_css:
+  - stylesheets/custom.css
+  - assets/Documenter.css
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+# TODO
+# https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
+#extra:
+#  version:
+#    provider: mike
+
+markdown_extensions:
+  - tables
+  - admonition
+  - toc:
+      permalink: "¤" # Adds a clickable permalink to each section heading
+      toc_depth: 4
+  - pymdownx.arithmatex: # Render LaTeX via MathJax
+      generic: true
+  - pymdownx.details # Allowing hidden expandable regions denoted by ???
+  - pymdownx.highlight
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences # Seems to enable syntax highlighting when used with the Material theme.
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - def_list
+  - pymdownx.tabbed:
+      alternate_style: true 
+  - attr_list
+  - md_in_html
+plugins:
+  - search # default search plugin; needs manually re-enabling when using any other plugins
+  - autorefs # Cross-links to headings
+  - include_exclude_files:
+      exclude:
+#        - "_overrides"
+#  - mknotebooks # Jupyter notebooks
+#  - mkdocs-video
+nav:
+  - "Home": "index.md"
+  - "First Steps with DataFrames": "./man/basics.md"
+  - "User Guide" :
+    - "Getting Started": "./man/getting_started.md"
+    - "Working with DataFrames": "./man/working_with_dataframes.md"
+    - "Importing and Exporting Data (I/O)": "./man/importing_and_exporting.md"
+    - "Joins": "./man/joins.md"
+    - "Split-apply-combine": "./man/split_apply_combine.md"
+    - "Reshaping": "./man/reshaping_and_pivoting.md"
+    - "Sorting": "./man/sorting.md"
+    - "Categorical Data": "./man/categorical.md"
+    - "Missing Data": "./man/missing.md"
+    - "Data manipulation frameworks": "./man/querying_frameworks.md"
+    - "Comparison with Python/R/Stata": "./man/comparisons.md"
+  - "API" :
+    - "Types": "./lib/types.md"
+    - "Functions": "./lib/functions.md"
+    - "Indexing": "./lib/indexing.md"
+    - "Metadata": "./lib/metadata.md"
+#    hide("Internals" => "lib/internals.md")