From 87edfa61c1757e3955c55e2d6eb72b52cae8d171 Mon Sep 17 00:00:00 2001 From: Roman Khavronenko Date: Tue, 25 Jun 2024 10:16:27 +0200 Subject: [PATCH] docs: add section for docs modification (#6528) While there, remove the obsolete files from the previous version of docs. Signed-off-by: hagen1778 --- README.md | 28 ++++++++++++- docs/CNAME | 1 - docs/CONTRIBUTING.md | 2 +- docs/Gemfile | 3 -- docs/Makefile | 10 ----- docs/_config.yml | 24 ----------- docs/_includes/extra/head.html | 2 - docs/_includes/extra/script.js | 72 -------------------------------- docs/_includes/extra/styles.scss | 64 ---------------------------- docs/googlec3812dcf278679ec.html | 1 - docs/robots.txt | 2 - 11 files changed, 28 insertions(+), 181 deletions(-) delete mode 100644 docs/CNAME delete mode 100644 docs/Gemfile delete mode 100644 docs/_config.yml delete mode 100644 docs/_includes/extra/head.html delete mode 100644 docs/_includes/extra/script.js delete mode 100644 docs/_includes/extra/styles.scss delete mode 100644 docs/googlec3812dcf278679ec.html delete mode 100644 docs/robots.txt diff --git a/README.md b/README.md index e7df2d59b..60a781186 100644 --- a/README.md +++ b/README.md @@ -2706,7 +2706,33 @@ If you like VictoriaMetrics and want to contribute, then please [read these docs Report bugs and propose new features [here](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). -## Images in documentation +## Documentation + +VictoriaMetrics documentation is available at [https://docs.victoriametrics.com/](https://docs.victoriametrics.com/). +It is built from `*.md` files located in [docs](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/docs) folder +and gets automatically updated once changes are merged to [master](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master) branch. +To update the documentation follow the steps below: +- [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) +VictoriaMetrics repo and apply changes to the docs: + - To update [the main page](https://docs.victoriametrics.com/) modify [this file](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/README.md). + - To update other pages, apply changes to the corresponding file in [docs folder](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/docs). +- If your changes contain an image then see [images in documentation](https://docs.victoriametrics.com/#images-in-documentation). +- Once changes are made, execute the command below to finalize and sync the changes: +```sh +make docs-sync +``` +- Create [a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) +with proposed changes and wait for it to be merged. + +Requirements for changes to docs: +- Keep backward compatibility of existing links. Avoid changing anchors or deleting pages as they could have been +used or posted in other docs, GitHub issues, stackoverlow answers, etc. +- Keep docs simple. Try using as simple wording as possible. +- Keep docs consistent. When modifying existing docs, verify that other places referencing to this doc are still relevant. +- Prefer improving the existing docs instead of adding new ones. +- Use absolute links. + +### Images in documentation Please, keep image size and number of images per single page low. Keep the docs page as lightweight as possible. diff --git a/docs/CNAME b/docs/CNAME deleted file mode 100644 index ff02137de..000000000 --- a/docs/CNAME +++ /dev/null @@ -1 +0,0 @@ -docs.victoriametrics.com \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3e55ea8a3..baad34968 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -17,7 +17,7 @@ If you like VictoriaMetrics and want to contribute, then it would be great: - Joining VictoriaMetrics community Slack ([Slack inviter](https://slack.victoriametrics.com/) and [Slack channel](https://victoriametrics.slack.com/)) and helping other community members there. - Filing issues, feature requests and questions [at VictoriaMetrics GitHub](https://github.com/VictoriaMetrics/VictoriaMetrics/issues). -- Improving [VictoriaMetrics docs](https://docs.victoriametrics.com/). The docs' sources are located [here](https://github.com/VictoriaMetrics/VictoriaMetrics/tree/master/docs). +- Improving [VictoriaMetrics docs](https://docs.victoriametrics.com/). See how to update docs [here](https://docs.victoriametrics.com/#documentation). - Spreading the word about VictoriaMetrics via various channels: - conference talks - blogposts, articles and [case studies](https://github.com/VictoriaMetrics/VictoriaMetrics/blob/master/docs/CaseStudies.md) diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index 73d01526e..000000000 --- a/docs/Gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source "https://rubygems.org" -gem "jekyll-rtd-theme", "~> 2.0.6" -gem "github-pages", group: :jekyll_plugins \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index af61bcba3..00d51c6e2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,15 +1,5 @@ # These commands must be run from the VictoriaMetrics repository root -# run local server for documentation website at http://127.0.0.1:4000/ -docs-up: - docker run --rm -it \ - -e JEKYLL_GITHUB_TOKEN=blank \ - -e PAGES_API_URL=http://0.0.0.0 \ - -e PAGES_REPO_NWO=VictoriaMetrics/VictoriaMetrics \ - -p 4000:4000 \ - -v $(shell pwd)/docs:/srv/jekyll \ - jekyll/jekyll:3.8 jekyll serve --livereload --incremental - # Converts images at docs folder to webp format # See https://docs.victoriametrics.com/single-server-victoriametrics/#images-in-documentation docs-images-to-webp: diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index a58d23767..000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,24 +0,0 @@ -title: VictoriaMetrics -author: VictoriaMetrics -email: info@victoriametrics.com -description: > - The High Performance Open Source Time Series Database & Monitoring Solution - -remote_theme: rundocs/jekyll-rtd-theme - -readme_index: - with_frontmatter: true - - -exclude: - # exclude assets/README.md from publishing on the docs website - # as its purpose is different to other docs. - - assets/README.md - -google: - gtag: G-N9SVT8S3HK - -plugins: - - github-pages - - diff --git a/docs/_includes/extra/head.html b/docs/_includes/extra/head.html deleted file mode 100644 index c317fa7c3..000000000 --- a/docs/_includes/extra/head.html +++ /dev/null @@ -1,2 +0,0 @@ - - \ No newline at end of file diff --git a/docs/_includes/extra/script.js b/docs/_includes/extra/script.js deleted file mode 100644 index 08c736cd4..000000000 --- a/docs/_includes/extra/script.js +++ /dev/null @@ -1,72 +0,0 @@ -/* When in mobile layout, the anchor navigation for submenus -* doesn't work due to fixed body height when menu is toggled. -* This script intercepts clicks on links, toggles the menu off -* and performs the anchor navigation. */ - -window.addEventListener("load", function () { - let href = window.location.pathname; - const hash = window.location.hash; - if (hash !== "") { - href = hash - } - const sidebar = document.querySelector('.sidebar .toctree'); - const selector = function (href) { - return `a[href="${href}"]` - }; - let element = sidebar.querySelector(selector(href)); - if (!element) { - href = window.location.pathname; - element = document.querySelector(selector(href)); - } - if (element) { - element.scrollIntoView({behavior: "smooth", block: "center", inline: "nearest"}); - } - addNewDocsButton() -}); - -function addNewDocsButton() { - let navigationBox = document.querySelector(".navigation-top"); - if (navigationBox) { - let newDocsButton = document.createElement('a'); - newDocsButton.appendChild(document.createTextNode("Try New Docs")); - newDocsButton.className = "btn"; - newDocsButton.title = "Try New Docs"; - newDocsButton.href = "https://new.docs.victoriametrics.com"; - let lastA = document.querySelector(".navigation-top > a"); - if (lastA) { - lastA.parentNode.insertBefore(newDocsButton, lastA); - } - } -} - -$(document).on("click", '.shift li.toc a', function (e) { - let segments = this.href.split('#'); - if (segments.length < 2) { - /* ignore links without anchor */ - return true; - } - - e.preventDefault(); - $("#toggle").click(); - setTimeout(function () { - location.hash = segments.pop(); - }, 1) -}); - -/* Clipboard-copy snippet from https://github.com/marcoaugustoandrade/jekyll-clipboardjs/blob/master/copy.js */ -let codes = document.querySelectorAll('.with-copy .highlight > pre > code'); -let countID = 0; -codes.forEach((code) => { - - code.setAttribute("id", "code" + countID); - - let btn = document.createElement('button'); - btn.innerHTML = "Copy"; - btn.className = "btn-copy"; - btn.setAttribute("data-clipboard-action", "copy"); - btn.setAttribute("data-clipboard-target", "#code" + countID); - code.before(btn); - countID++; -}); - -let clipboard = new ClipboardJS('.btn-copy'); diff --git a/docs/_includes/extra/styles.scss b/docs/_includes/extra/styles.scss deleted file mode 100644 index 7344cb1b2..000000000 --- a/docs/_includes/extra/styles.scss +++ /dev/null @@ -1,64 +0,0 @@ -* { - box-sizing: border-box !important; - font-family: 'Lato', sans-serif; -} - -@media (min-width: 1280px) { - .content-wrap { - max-width: none; - } -} - -// Logo -.fa-home{ - vertical-align: middle; - width: 14px; -} - -.fa-home:before { - content: url(../assets/images/vm_logo.svg); -} - -// Navigation -.header { - background: black; -} - -.toctree .caption { - color: #fc5d20 !important; -} - -.toctree .fa { - margin-right: 5px; -} - -// Footer -.status .branch .name{ - color: #b35cec !important; -} - -// hidden in menu pages -[data-sort="-1"] { - display: none; -} - -// Content -.markdown-body h1, -.markdown-body h2, -.markdown-body h3, -.markdown-body h4 { - font-family: 'Lato', sans-serif !important; -} - -// try new page button -.navigation-top { - min-height: 32px; -} - -.navigation-top > a:last-child{ - padding-left: 5px -} - -.navigation-top > .btn { - margin-left: auto -} \ No newline at end of file diff --git a/docs/googlec3812dcf278679ec.html b/docs/googlec3812dcf278679ec.html deleted file mode 100644 index 90b12b87e..000000000 --- a/docs/googlec3812dcf278679ec.html +++ /dev/null @@ -1 +0,0 @@ -google-site-verification: googlec3812dcf278679ec.html \ No newline at end of file diff --git a/docs/robots.txt b/docs/robots.txt deleted file mode 100644 index 09c37fed5..000000000 --- a/docs/robots.txt +++ /dev/null @@ -1,2 +0,0 @@ -user-agent: * -allow: /