From 9638fd8459e56221c23180860009360fb1fb4bbd Mon Sep 17 00:00:00 2001 From: Lazaro Alonso Date: Fri, 11 Aug 2023 22:54:30 +0200 Subject: [PATCH] new docs, complete --- .github/workflows/Documenter.yml | 33 +++++++ .github/workflows/ci.yml | 11 --- .gitignore | 15 +++- docs/Project.toml | 2 + docs/make.jl | 66 +++++--------- docs/mkdocs.yml | 143 +++++++++++++++++++++++++++++++ docs/src/index.md | 57 +++++++++--- docs/src/javascripts/mathjax.js | 16 ++++ docs/src/stylesheets/custom.css | 120 ++++++++++++++++++++++++++ 9 files changed, 390 insertions(+), 73 deletions(-) create mode 100644 .github/workflows/Documenter.yml create mode 100644 docs/mkdocs.yml create mode 100644 docs/src/javascripts/mathjax.js create mode 100644 docs/src/stylesheets/custom.css diff --git a/.github/workflows/Documenter.yml b/.github/workflows/Documenter.yml new file mode 100644 index 0000000000..252f8039c6 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4222741a09..e039679cbe 100644 --- a/.github/workflows/ci.yml +++ b/.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 }} diff --git a/.gitignore b/.gitignore index 1692e5af39..9a40db4774 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file diff --git a/docs/Project.toml b/docs/Project.toml index ebe348a76b..549439e9af 100755 --- a/docs/Project.toml +++ b/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" diff --git a/docs/make.jl b/docs/make.jl index fa64782dac..f22f99e817 100644 --- a/docs/make.jl +++ b/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") diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000000..6b7b963315 --- /dev/null +++ b/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") \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index 1d7511908a..1fb2e59897 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,13 +1,24 @@ -# DataFrames.jl + -Welcome to the DataFrames.jl documentation! +## DataFrames.jl -This resource aims to teach you everything you need to know to get up and -running with tabular data manipulation using the DataFrames.jl package. +Welcome to the `DataFrames.jl `documentation! -For more illustrations of DataFrames.jl usage, in particular in conjunction with +This resource aims to teach you everything you need to know to get up and +running with tabular data manipulation using the `DataFrames.jl` package. + +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/JuliaData/DataFrames.jl/blob/main/LICENSE) +[![docs-latest-img](https://img.shields.io/badge/docs-latest-blue.svg)](http://dataframes.juliadata.org/latest/) +[![docs-stable-img](https://img.shields.io/badge/docs-stable-blue.svg)](http://dataframes.juliadata.org/stable/) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7632427.svg)](https://doi.org/10.5281/zenodo.7632427) +[![Downloads](https://shields.io/endpoint?url=https://pkgs.genieframework.com/api/v1/badge/DataFrames&label=Downloads)](https://pkgs.genieframework.com?packages=DataFrames) +[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) +[![Coverage Status](http://codecov.io/github/JuliaData/DataFrames.jl/coverage.svg?branch=main)](http://codecov.io/github/JuliaData/DataFrames.jl?branch=main) +[![CI Testing](https://github.com/JuliaData/DataFrames.jl/workflows/CI/badge.svg)](https://github.com/JuliaData/DataFrames.jl/actions?query=workflow%3ACI+branch%3Amain) + +For more illustrations of `DataFrames.jl` usage, in particular in conjunction with other packages you can check-out the following resources -(they are kept up to date with the released version of DataFrames.jl): +(they are kept up to date with the released version of `DataFrames.jl`): * [Data Wrangling with DataFrames.jl Cheat Sheet](https://www.ahsmart.com/pub/data-wrangling-with-data-frames-jl-cheat-sheet/) * [DataFrames Tutorial using Jupyter Notebooks](https://github.com/bkamins/Julia-DataFrames-Tutorial/) * [Julia Academy DataFrames.jl tutorial](https://github.com/JuliaAcademy/DataFrames) @@ -64,8 +75,8 @@ a list of well-supported libraries that provide different data science tools, along with a few notes about what makes each library special, and how well integrated they are with DataFrames.jl. - -- **Statistics** +```@raw html +??? tip "**Statistics**" - [StatsKit.jl](https://github.com/JuliaStats/StatsKit.jl): A convenience meta-package which loads a set of essential packages for statistics, including those mentioned below in this section and DataFrames.jl itself. @@ -92,7 +103,10 @@ integrated they are with DataFrames.jl. linear regression, ridge regression, PCA, component analyses tools. Not well integrated with DataFrames.jl, but easily used in combination with `StatsModels`. -- **Machine Learning** +``` + +```@raw html +??? tip "**Machine Learning**" - [MLJ.jl](https://github.com/alan-turing-institute/MLJ.jl): if you're more of an applied user, there is a single package the pulls from all these different libraries and provides a single, scikit-learn @@ -111,7 +125,10 @@ integrated they are with DataFrames.jl. - Deep learning: [KNet.jl](https://denizyuret.github.io/Knet.jl/stable/tutorial/#Introduction-to-Knet-1) and [Flux.jl](https://github.com/FluxML/Flux.jl). -- **Plotting** +``` + +```@raw html +??? tip "**Plotting**" - [Plots.jl](http://docs.juliaplots.org/latest/): Powerful, modern plotting library with a syntax akin to that of [matplotlib](https://matplotlib.org/) (in Python) or `plot` (in R). @@ -125,7 +142,10 @@ integrated they are with DataFrames.jl. - [VegaLite.jl](https://www.queryverse.org/VegaLite.jl/stable/): High-level plotting library that uses a different "grammar of graphics" syntax and has an emphasis on interactive graphics. -- **Data Wrangling**: +``` + +```@raw html +??? tip "**Data Wrangling**" - [Impute.jl](https://github.com/invenia/Impute.jl): various methods for handling missing data in vectors, matrices and tables. - [DataFramesMeta.jl](https://github.com/JuliaData/DataFramesMeta.jl): @@ -142,13 +162,19 @@ integrated they are with DataFrames.jl. dplyr in R or [LINQ](https://en.wikipedia.org/wiki/Language_Integrated_Query). - You can find more information on these packages in the [Data manipulation frameworks](@ref) section of this manual. -- **And More!** +``` + +```@raw html +??? tip "**And More!**" - [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl): A pure-Julia, high performance network analysis library. Edgelists in `DataFrame`s can be easily converted into graphs using the [GraphDataFrameBridge.jl](https://github.com/JuliaGraphs/GraphDataFrameBridge.jl) package. -- **IO**: +``` + +```@raw html +??? tip "**IO**" - DataFrames.jl work well with a range of formats, including: - CSV files (using [CSV.jl](https://github.com/JuliaData/CSV.jl)), - Apache Arrow (using [Arrow.jl](https://github.com/JuliaData/Arrow.jl)) @@ -158,6 +184,7 @@ integrated they are with DataFrames.jl. - Parquet files (using [Parquet2.jl](https://gitlab.com/ExpandingMan/Parquet2.jl)), - reading R data files (.rda, .RData) (using [RData.jl](https://github.com/JuliaData/RData.jl)). +``` While not all of these libraries are tightly integrated with DataFrames.jl, because `DataFrame`s are essentially collections of aligned Julia vectors, so it @@ -237,7 +264,8 @@ all such objects are documented in this manual (in case some documentation is missing please kindly report an issue [here](https://github.com/JuliaData/DataFrames.jl/issues/new)). -!!! note +```@raw html +??? warning "Breaking changes" Breaking changes to public and documented API are avoided in DataFrames.jl where possible. @@ -287,6 +315,7 @@ missing please kindly report an issue wanted); * the change is needed to adjust DataFrames.jl functionality to changes in Base Julia. +``` Please be warned that while Julia allows you to access internal functions or types of DataFrames.jl these can change without warning between versions of diff --git a/docs/src/javascripts/mathjax.js b/docs/src/javascripts/mathjax.js new file mode 100644 index 0000000000..a80ddbff75 --- /dev/null +++ b/docs/src/javascripts/mathjax.js @@ -0,0 +1,16 @@ +window.MathJax = { + tex: { + inlineMath: [["\\(", "\\)"]], + displayMath: [["\\[", "\\]"]], + processEscapes: true, + processEnvironments: true + }, + options: { + ignoreHtmlClass: ".*|", + processHtmlClass: "arithmatex" + } +}; + +document$.subscribe(() => { + MathJax.typesetPromise() +}) \ No newline at end of file diff --git a/docs/src/stylesheets/custom.css b/docs/src/stylesheets/custom.css new file mode 100644 index 0000000000..a3c6c1b0f6 --- /dev/null +++ b/docs/src/stylesheets/custom.css @@ -0,0 +1,120 @@ +/* Fix /page#foo going to the top of the viewport and being hidden by the navbar */ +html { + scroll-padding-top: 50px; + } + + /* Fit the Twitter handle alongside the GitHub one in the top right. */ + + div.md-header__source { + width: revert; + max-width: revert; + } + + a.md-source { + display: inline-block; + } + + .md-source__repository { + max-width: 100%; + } + + /* Emphasise sections of nav on left hand side */ + + nav.md-nav { + padding-left: 5px; + } + + nav.md-nav--secondary { + border-left: revert !important; + } + + .md-nav__title { + font-size: 0.9rem; + } + + .md-nav__item--section > .md-nav__link { + font-size: 0.9rem; + } + + /* Indent autogenerated documentation */ + + div.doc-contents { + padding-left: 25px; + border-left: 4px solid rgba(230, 230, 230); + } + + /* Increase visibility of splitters "---" */ + + [data-md-color-scheme="default"] .md-typeset hr { + border-bottom-color: rgb(0, 0, 0); + border-bottom-width: 1pt; + } + + [data-md-color-scheme="slate"] .md-typeset hr { + border-bottom-color: rgb(230, 230, 230); + } + + /* More space at the bottom of the page */ + + .md-main__inner { + margin-bottom: 1.5rem; + } + + /* Remove prev/next footer buttons */ + + .md-footer__inner { + display: none; + } + + /* Bugfix: remove the superfluous parts generated when doing: + + ??? Blah + + ::: library.something + */ + + .md-typeset details .mkdocstrings > h4 { + display: none; + } + + .md-typeset details .mkdocstrings > h5 { + display: none; + } + + /* Change default colours for tags */ + + [data-md-color-scheme="default"] { + --md-typeset-a-color: #9558B2 !important; + } + [data-md-color-scheme="slate"] { + --md-typeset-a-color: #b5df1d !important; + } + + /* Highlight functions, classes etc. type signatures. Really helps to make clear where + one item ends and another begins. */ + + [data-md-color-scheme="default"] { + --doc-heading-color: #DDD; + --doc-heading-border-color: #CCC; + --doc-heading-color-alt: #F0F0F0; + } + [data-md-color-scheme="slate"] { + --doc-heading-color: rgb(25,25,33); + --doc-heading-border-color: rgb(25,25,33); + --doc-heading-color-alt: rgb(33,33,44); + --md-code-bg-color: rgb(38,38,50); + } + + h4.doc-heading { + /* NOT var(--md-code-bg-color) as that's not visually distinct from other code blocks.*/ + background-color: var(--doc-heading-color); + border: solid var(--doc-heading-border-color); + border-width: 1.5pt; + border-radius: 2pt; + padding: 0pt 5pt 2pt 5pt; + } + h5.doc-heading, h6.heading { + background-color: var(--doc-heading-color-alt); + border-radius: 2pt; + padding: 0pt 5pt 2pt 5pt; + } \ No newline at end of file