diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 000000000..9c2def39e --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,84 @@ +name: Deploy Hugo site to Pages + +on: + push: + branches: + - dev + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +defaults: + run: + shell: bash + +jobs: + build: + runs-on: ubuntu-latest + env: + HUGO_VERSION: 0.128.0 + steps: + - name: Install Hugo CLI + run: | + wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \ + && sudo dpkg -i ${{ runner.temp }}/hugo.deb + hugo version + - name: Install Dart Sass + run: sudo snap install dart-sass + - name: Checkout + uses: actions/checkout@v4 + with: + submodules: recursive + fetch-depth: 0 + - name: Setup Pages + id: pages + uses: actions/configure-pages@v4 + - name: Install Node.js + uses: actions/setup-node@v3 + with: + node-version: 20 + - name: Install Node.js dependencies + run: | + cd docs + echo "npm install -g postcss postcss-cli autoprefixer" + npm i + [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true + - name: Build with Hugo + env: + # For maximum backward compatibility with Hugo modules + HUGO_ENVIRONMENT: production + HUGO_ENV: production + TZ: America/Los_Angeles + run: | + cd docs + hugo \ + --gc \ + --minify \ + --baseURL "${{ steps.pages.outputs.base_url }}/" + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./docs/public + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 6b8081823..fa21c8285 100644 --- a/.gitignore +++ b/.gitignore @@ -34,5 +34,4 @@ out/ vendor/ -docs/_* .DS_Store diff --git a/.mapping.json b/.mapping.json index 4434395ce..22bdea19b 100644 --- a/.mapping.json +++ b/.mapping.json @@ -29,6 +29,7 @@ ".changes/v0.5.29.md":"load/projects/pandora/.changes/v0.5.29.md", ".changie.yaml":"load/projects/pandora/.changie.yaml", ".github/actions/setup-yc/action.yml":"load/projects/pandora/.github/actions/setup-yc/action.yml", + ".github/workflows/pages.yml":"load/projects/pandora/.github/workflows/pages.yml", ".github/workflows/release.yml":"load/projects/pandora/.github/workflows/release.yml", ".github/workflows/test.yml":"load/projects/pandora/.github/workflows/test.yml", ".github/workflows/yc.yml":"load/projects/pandora/.github/workflows/yc.yml", @@ -263,57 +264,165 @@ "debian/copyright":"load/projects/pandora/debian/copyright", "debian/rules":"load/projects/pandora/debian/rules", "debian/source/format":"load/projects/pandora/debian/source/format", - "docs/eng/architecture.md":"load/projects/pandora/docs/eng/architecture.md", - "docs/eng/best-practices.md":"load/projects/pandora/docs/eng/best-practices.md", - "docs/eng/best_practices/discard-overflow.md":"load/projects/pandora/docs/eng/best_practices/discard-overflow.md", - "docs/eng/best_practices/rps-per-instance.md":"load/projects/pandora/docs/eng/best_practices/rps-per-instance.md", - "docs/eng/best_practices/shared-client.md":"load/projects/pandora/docs/eng/best_practices/shared-client.md", - "docs/eng/config.md":"load/projects/pandora/docs/eng/config.md", - "docs/eng/custom.md":"load/projects/pandora/docs/eng/custom.md", - "docs/eng/grpc-generator.md":"load/projects/pandora/docs/eng/grpc-generator.md", - "docs/eng/http-generator.md":"load/projects/pandora/docs/eng/http-generator.md", - "docs/eng/install.md":"load/projects/pandora/docs/eng/install.md", - "docs/eng/load-profile.md":"load/projects/pandora/docs/eng/load-profile.md", - "docs/eng/performance.md":"load/projects/pandora/docs/eng/performance.md", - "docs/eng/providers.md":"load/projects/pandora/docs/eng/providers.md", - "docs/eng/scenario-grpc-generator.md":"load/projects/pandora/docs/eng/scenario-grpc-generator.md", - "docs/eng/scenario-http-generator.md":"load/projects/pandora/docs/eng/scenario-http-generator.md", - "docs/eng/scenario/functions.md":"load/projects/pandora/docs/eng/scenario/functions.md", - "docs/eng/scenario/locals.md":"load/projects/pandora/docs/eng/scenario/locals.md", - "docs/eng/scenario/variable_source.md":"load/projects/pandora/docs/eng/scenario/variable_source.md", - "docs/eng/startup.md":"load/projects/pandora/docs/eng/startup.md", - "docs/eng/tutorial.md":"load/projects/pandora/docs/eng/tutorial.md", - "docs/images/architecture.graphml":"load/projects/pandora/docs/images/architecture.graphml", - "docs/images/architecture.png":"load/projects/pandora/docs/images/architecture.png", - "docs/images/http_100kb_net.png":"load/projects/pandora/docs/images/http_100kb_net.png", - "docs/images/http_connection_close_td.png":"load/projects/pandora/docs/images/http_connection_close_td.png", - "docs/images/http_delay_10s_instances.png":"load/projects/pandora/docs/images/http_delay_10s_instances.png", - "docs/images/http_delay_10s_td.png":"load/projects/pandora/docs/images/http_delay_10s_td.png", - "docs/images/http_keep_alive_td.png":"load/projects/pandora/docs/images/http_keep_alive_td.png", - "docs/images/http_srv_fail_q.png":"load/projects/pandora/docs/images/http_srv_fail_q.png", - "docs/images/scn_cases.png":"load/projects/pandora/docs/images/scn_cases.png", - "docs/index.md":"load/projects/pandora/docs/index.md", - "docs/rus/architecture.md":"load/projects/pandora/docs/rus/architecture.md", - "docs/rus/best-practices.md":"load/projects/pandora/docs/rus/best-practices.md", - "docs/rus/best_practices/discard-overflow.md":"load/projects/pandora/docs/rus/best_practices/discard-overflow.md", - "docs/rus/best_practices/rps-per-instance.md":"load/projects/pandora/docs/rus/best_practices/rps-per-instance.md", - "docs/rus/best_practices/shared-client.md":"load/projects/pandora/docs/rus/best_practices/shared-client.md", - "docs/rus/config.md":"load/projects/pandora/docs/rus/config.md", - "docs/rus/custom.md":"load/projects/pandora/docs/rus/custom.md", - "docs/rus/grpc-generator.md":"load/projects/pandora/docs/rus/grpc-generator.md", - "docs/rus/http-generator.md":"load/projects/pandora/docs/rus/http-generator.md", - "docs/rus/index.md":"load/projects/pandora/docs/rus/index.md", - "docs/rus/install.md":"load/projects/pandora/docs/rus/install.md", - "docs/rus/load-profile.md":"load/projects/pandora/docs/rus/load-profile.md", - "docs/rus/performance.md":"load/projects/pandora/docs/rus/performance.md", - "docs/rus/providers.md":"load/projects/pandora/docs/rus/providers.md", - "docs/rus/scenario-grpc-generator.md":"load/projects/pandora/docs/rus/scenario-grpc-generator.md", - "docs/rus/scenario-http-generator.md":"load/projects/pandora/docs/rus/scenario-http-generator.md", - "docs/rus/scenario/functions.md":"load/projects/pandora/docs/rus/scenario/functions.md", - "docs/rus/scenario/locals.md":"load/projects/pandora/docs/rus/scenario/locals.md", - "docs/rus/scenario/variable_source.md":"load/projects/pandora/docs/rus/scenario/variable_source.md", - "docs/rus/startup.md":"load/projects/pandora/docs/rus/startup.md", - "docs/rus/tutorial.md":"load/projects/pandora/docs/rus/tutorial.md", + "docs/.cspell.yml":"load/projects/pandora/docs/.cspell.yml", + "docs/.gitignore":"load/projects/pandora/docs/.gitignore", + "docs/.nvmrc":"load/projects/pandora/docs/.nvmrc", + "docs/README.md":"load/projects/pandora/docs/README.md", + "docs/assets/scss/_variables_project.scss":"load/projects/pandora/docs/assets/scss/_variables_project.scss", + "docs/config.yaml":"load/projects/pandora/docs/config.yaml", + "docs/content/en/_index.md":"load/projects/pandora/docs/content/en/_index.md", + "docs/content/en/architecture.md":"load/projects/pandora/docs/content/en/architecture.md", + "docs/content/en/best-practices/_index.md":"load/projects/pandora/docs/content/en/best-practices/_index.md", + "docs/content/en/best-practices/discard-overflow.md":"load/projects/pandora/docs/content/en/best-practices/discard-overflow.md", + "docs/content/en/best-practices/rps-per-instance.md":"load/projects/pandora/docs/content/en/best-practices/rps-per-instance.md", + "docs/content/en/best-practices/shared-client.md":"load/projects/pandora/docs/content/en/best-practices/shared-client.md", + "docs/content/en/config.md":"load/projects/pandora/docs/content/en/config.md", + "docs/content/en/custom.md":"load/projects/pandora/docs/content/en/custom.md", + "docs/content/en/grpc-generator.md":"load/projects/pandora/docs/content/en/grpc-generator.md", + "docs/content/en/http-generator.md":"load/projects/pandora/docs/content/en/http-generator.md", + "docs/content/en/install.md":"load/projects/pandora/docs/content/en/install.md", + "docs/content/en/load-profile.md":"load/projects/pandora/docs/content/en/load-profile.md", + "docs/content/en/performance.md":"load/projects/pandora/docs/content/en/performance.md", + "docs/content/en/providers.md":"load/projects/pandora/docs/content/en/providers.md", + "docs/content/en/scenario-grpc-generator.md":"load/projects/pandora/docs/content/en/scenario-grpc-generator.md", + "docs/content/en/scenario-http-generator.md":"load/projects/pandora/docs/content/en/scenario-http-generator.md", + "docs/content/en/scenario/_index.md":"load/projects/pandora/docs/content/en/scenario/_index.md", + "docs/content/en/scenario/functions.md":"load/projects/pandora/docs/content/en/scenario/functions.md", + "docs/content/en/scenario/locals.md":"load/projects/pandora/docs/content/en/scenario/locals.md", + "docs/content/en/scenario/variable_source.md":"load/projects/pandora/docs/content/en/scenario/variable_source.md", + "docs/content/en/search.md":"load/projects/pandora/docs/content/en/search.md", + "docs/content/en/startup.md":"load/projects/pandora/docs/content/en/startup.md", + "docs/content/en/tutorial.md":"load/projects/pandora/docs/content/en/tutorial.md", + "docs/content/ru/_index.md":"load/projects/pandora/docs/content/ru/_index.md", + "docs/content/ru/architecture.md":"load/projects/pandora/docs/content/ru/architecture.md", + "docs/content/ru/best-practices/_index.md":"load/projects/pandora/docs/content/ru/best-practices/_index.md", + "docs/content/ru/best-practices/discard-overflow.md":"load/projects/pandora/docs/content/ru/best-practices/discard-overflow.md", + "docs/content/ru/best-practices/rps-per-instance.md":"load/projects/pandora/docs/content/ru/best-practices/rps-per-instance.md", + "docs/content/ru/best-practices/shared-client.md":"load/projects/pandora/docs/content/ru/best-practices/shared-client.md", + "docs/content/ru/config.md":"load/projects/pandora/docs/content/ru/config.md", + "docs/content/ru/custom.md":"load/projects/pandora/docs/content/ru/custom.md", + "docs/content/ru/grpc-generator.md":"load/projects/pandora/docs/content/ru/grpc-generator.md", + "docs/content/ru/http-generator.md":"load/projects/pandora/docs/content/ru/http-generator.md", + "docs/content/ru/install.md":"load/projects/pandora/docs/content/ru/install.md", + "docs/content/ru/load-profile.md":"load/projects/pandora/docs/content/ru/load-profile.md", + "docs/content/ru/performance.md":"load/projects/pandora/docs/content/ru/performance.md", + "docs/content/ru/providers.md":"load/projects/pandora/docs/content/ru/providers.md", + "docs/content/ru/scenario-grpc-generator.md":"load/projects/pandora/docs/content/ru/scenario-grpc-generator.md", + "docs/content/ru/scenario-http-generator.md":"load/projects/pandora/docs/content/ru/scenario-http-generator.md", + "docs/content/ru/scenario/_index.md":"load/projects/pandora/docs/content/ru/scenario/_index.md", + "docs/content/ru/scenario/functions.md":"load/projects/pandora/docs/content/ru/scenario/functions.md", + "docs/content/ru/scenario/locals.md":"load/projects/pandora/docs/content/ru/scenario/locals.md", + "docs/content/ru/scenario/variable_source.md":"load/projects/pandora/docs/content/ru/scenario/variable_source.md", + "docs/content/ru/search.md":"load/projects/pandora/docs/content/ru/search.md", + "docs/content/ru/startup.md":"load/projects/pandora/docs/content/ru/startup.md", + "docs/content/ru/tutorial.md":"load/projects/pandora/docs/content/ru/tutorial.md", + "docs/docsy.work":"load/projects/pandora/docs/docsy.work", + "docs/docsy.work.sum":"load/projects/pandora/docs/docsy.work.sum", + "docs/go.mod":"load/projects/pandora/docs/go.mod", + "docs/go.sum":"load/projects/pandora/docs/go.sum", + "docs/hugo-disabled.toml":"load/projects/pandora/docs/hugo-disabled.toml", + "docs/hugo.yaml":"load/projects/pandora/docs/hugo.yaml", + "docs/layouts/404.html":"load/projects/pandora/docs/layouts/404.html", + "docs/layouts/_default/_markup/render-codeblock-chem.html":"load/projects/pandora/docs/layouts/_default/_markup/render-codeblock-chem.html", + "docs/layouts/_default/_markup/render-codeblock-math.html":"load/projects/pandora/docs/layouts/_default/_markup/render-codeblock-math.html", + "docs/layouts/_default/_markup/render-codeblock-mermaid.html":"load/projects/pandora/docs/layouts/_default/_markup/render-codeblock-mermaid.html", + "docs/layouts/_default/_markup/td-render-heading.html":"load/projects/pandora/docs/layouts/_default/_markup/td-render-heading.html", + "docs/layouts/_default/baseof.html":"load/projects/pandora/docs/layouts/_default/baseof.html", + "docs/layouts/_default/content.html":"load/projects/pandora/docs/layouts/_default/content.html", + "docs/layouts/_default/list.html":"load/projects/pandora/docs/layouts/_default/list.html", + "docs/layouts/_default/search.html":"load/projects/pandora/docs/layouts/_default/search.html", + "docs/layouts/_default/single.html":"load/projects/pandora/docs/layouts/_default/single.html", + "docs/layouts/_default/taxonomy.html":"load/projects/pandora/docs/layouts/_default/taxonomy.html", + "docs/layouts/_default/terms.html":"load/projects/pandora/docs/layouts/_default/terms.html", + "docs/layouts/_internal/google_analytics.html":"load/projects/pandora/docs/layouts/_internal/google_analytics.html", + "docs/layouts/blog/baseof.html":"load/projects/pandora/docs/layouts/blog/baseof.html", + "docs/layouts/blog/baseof.print.html":"load/projects/pandora/docs/layouts/blog/baseof.print.html", + "docs/layouts/blog/content.html":"load/projects/pandora/docs/layouts/blog/content.html", + "docs/layouts/blog/list.html":"load/projects/pandora/docs/layouts/blog/list.html", + "docs/layouts/blog/section.print.html":"load/projects/pandora/docs/layouts/blog/section.print.html", + "docs/layouts/blog/single.html":"load/projects/pandora/docs/layouts/blog/single.html", + "docs/layouts/community/list.html":"load/projects/pandora/docs/layouts/community/list.html", + "docs/layouts/docs/baseof.html":"load/projects/pandora/docs/layouts/docs/baseof.html", + "docs/layouts/docs/baseof.print.html":"load/projects/pandora/docs/layouts/docs/baseof.print.html", + "docs/layouts/docs/list.html":"load/projects/pandora/docs/layouts/docs/list.html", + "docs/layouts/docs/list.print.html":"load/projects/pandora/docs/layouts/docs/list.print.html", + "docs/layouts/docs/single.html":"load/projects/pandora/docs/layouts/docs/single.html", + "docs/layouts/home.html":"load/projects/pandora/docs/layouts/home.html", + "docs/layouts/partials/breadcrumb.html":"load/projects/pandora/docs/layouts/partials/breadcrumb.html", + "docs/layouts/partials/community_links.html":"load/projects/pandora/docs/layouts/partials/community_links.html", + "docs/layouts/partials/disqus-comment.html":"load/projects/pandora/docs/layouts/partials/disqus-comment.html", + "docs/layouts/partials/favicons.html":"load/projects/pandora/docs/layouts/partials/favicons.html", + "docs/layouts/partials/featured-image.html":"load/projects/pandora/docs/layouts/partials/featured-image.html", + "docs/layouts/partials/feedback.html":"load/projects/pandora/docs/layouts/partials/feedback.html", + "docs/layouts/partials/footer.html":"load/projects/pandora/docs/layouts/partials/footer.html", + "docs/layouts/partials/footer/center.html":"load/projects/pandora/docs/layouts/partials/footer/center.html", + "docs/layouts/partials/footer/copyright.html":"load/projects/pandora/docs/layouts/partials/footer/copyright.html", + "docs/layouts/partials/footer/left.html":"load/projects/pandora/docs/layouts/partials/footer/left.html", + "docs/layouts/partials/footer/links.html":"load/projects/pandora/docs/layouts/partials/footer/links.html", + "docs/layouts/partials/footer/right.html":"load/projects/pandora/docs/layouts/partials/footer/right.html", + "docs/layouts/partials/head-css.html":"load/projects/pandora/docs/layouts/partials/head-css.html", + "docs/layouts/partials/head.html":"load/projects/pandora/docs/layouts/partials/head.html", + "docs/layouts/partials/hooks/body-end.html":"load/projects/pandora/docs/layouts/partials/hooks/body-end.html", + "docs/layouts/partials/hooks/head-end.html":"load/projects/pandora/docs/layouts/partials/hooks/head-end.html", + "docs/layouts/partials/navbar-lang-selector.html":"load/projects/pandora/docs/layouts/partials/navbar-lang-selector.html", + "docs/layouts/partials/navbar-version-selector.html":"load/projects/pandora/docs/layouts/partials/navbar-version-selector.html", + "docs/layouts/partials/navbar.html":"load/projects/pandora/docs/layouts/partials/navbar.html", + "docs/layouts/partials/outputformat.html":"load/projects/pandora/docs/layouts/partials/outputformat.html", + "docs/layouts/partials/page-description.html":"load/projects/pandora/docs/layouts/partials/page-description.html", + "docs/layouts/partials/page-meta-lastmod.html":"load/projects/pandora/docs/layouts/partials/page-meta-lastmod.html", + "docs/layouts/partials/page-meta-links.html":"load/projects/pandora/docs/layouts/partials/page-meta-links.html", + "docs/layouts/partials/pager.html":"load/projects/pandora/docs/layouts/partials/pager.html", + "docs/layouts/partials/print/content-blog.html":"load/projects/pandora/docs/layouts/partials/print/content-blog.html", + "docs/layouts/partials/print/content.html":"load/projects/pandora/docs/layouts/partials/print/content.html", + "docs/layouts/partials/print/page-heading.html":"load/projects/pandora/docs/layouts/partials/print/page-heading.html", + "docs/layouts/partials/print/render.html":"load/projects/pandora/docs/layouts/partials/print/render.html", + "docs/layouts/partials/print/toc-li-blog.html":"load/projects/pandora/docs/layouts/partials/print/toc-li-blog.html", + "docs/layouts/partials/print/toc-li.html":"load/projects/pandora/docs/layouts/partials/print/toc-li.html", + "docs/layouts/partials/reading-time.html":"load/projects/pandora/docs/layouts/partials/reading-time.html", + "docs/layouts/partials/scripts.html":"load/projects/pandora/docs/layouts/partials/scripts.html", + "docs/layouts/partials/scripts/mermaid.html":"load/projects/pandora/docs/layouts/partials/scripts/mermaid.html", + "docs/layouts/partials/search-input.html":"load/projects/pandora/docs/layouts/partials/search-input.html", + "docs/layouts/partials/section-index.html":"load/projects/pandora/docs/layouts/partials/section-index.html", + "docs/layouts/partials/sidebar-tree.html":"load/projects/pandora/docs/layouts/partials/sidebar-tree.html", + "docs/layouts/partials/sidebar.html":"load/projects/pandora/docs/layouts/partials/sidebar.html", + "docs/layouts/partials/taxonomy_terms_article.html":"load/projects/pandora/docs/layouts/partials/taxonomy_terms_article.html", + "docs/layouts/partials/taxonomy_terms_article_wrapper.html":"load/projects/pandora/docs/layouts/partials/taxonomy_terms_article_wrapper.html", + "docs/layouts/partials/taxonomy_terms_cloud.html":"load/projects/pandora/docs/layouts/partials/taxonomy_terms_cloud.html", + "docs/layouts/partials/taxonomy_terms_clouds.html":"load/projects/pandora/docs/layouts/partials/taxonomy_terms_clouds.html", + "docs/layouts/partials/theme-toggler.html":"load/projects/pandora/docs/layouts/partials/theme-toggler.html", + "docs/layouts/partials/toc.html":"load/projects/pandora/docs/layouts/partials/toc.html", + "docs/layouts/partials/version-banner.html":"load/projects/pandora/docs/layouts/partials/version-banner.html", + "docs/layouts/shortcodes/alert.html":"load/projects/pandora/docs/layouts/shortcodes/alert.html", + "docs/layouts/shortcodes/blocks/cover.html":"load/projects/pandora/docs/layouts/shortcodes/blocks/cover.html", + "docs/layouts/shortcodes/blocks/feature.html":"load/projects/pandora/docs/layouts/shortcodes/blocks/feature.html", + "docs/layouts/shortcodes/blocks/lead.html":"load/projects/pandora/docs/layouts/shortcodes/blocks/lead.html", + "docs/layouts/shortcodes/blocks/link-down.html":"load/projects/pandora/docs/layouts/shortcodes/blocks/link-down.html", + "docs/layouts/shortcodes/blocks/section.html":"load/projects/pandora/docs/layouts/shortcodes/blocks/section.html", + "docs/layouts/shortcodes/card.html":"load/projects/pandora/docs/layouts/shortcodes/card.html", + "docs/layouts/shortcodes/cardpane.html":"load/projects/pandora/docs/layouts/shortcodes/cardpane.html", + "docs/layouts/shortcodes/conditional-text.html":"load/projects/pandora/docs/layouts/shortcodes/conditional-text.html", + "docs/layouts/shortcodes/figure.html":"load/projects/pandora/docs/layouts/shortcodes/figure.html", + "docs/layouts/shortcodes/iframe.html":"load/projects/pandora/docs/layouts/shortcodes/iframe.html", + "docs/layouts/shortcodes/imgproc.html":"load/projects/pandora/docs/layouts/shortcodes/imgproc.html", + "docs/layouts/shortcodes/pageinfo.html":"load/projects/pandora/docs/layouts/shortcodes/pageinfo.html", + "docs/layouts/shortcodes/readfile.html":"load/projects/pandora/docs/layouts/shortcodes/readfile.html", + "docs/layouts/shortcodes/redoc.html":"load/projects/pandora/docs/layouts/shortcodes/redoc.html", + "docs/layouts/shortcodes/swaggerui.html":"load/projects/pandora/docs/layouts/shortcodes/swaggerui.html", + "docs/layouts/shortcodes/tab.html":"load/projects/pandora/docs/layouts/shortcodes/tab.html", + "docs/layouts/shortcodes/tabpane.html":"load/projects/pandora/docs/layouts/shortcodes/tabpane.html", + "docs/layouts/swagger/baseof.html":"load/projects/pandora/docs/layouts/swagger/baseof.html", + "docs/layouts/swagger/list.html":"load/projects/pandora/docs/layouts/swagger/list.html", + "docs/layouts/swagger/single.html":"load/projects/pandora/docs/layouts/swagger/single.html", + "docs/package.json":"load/projects/pandora/docs/package.json", + "docs/static/images/architecture.graphml":"load/projects/pandora/docs/static/images/architecture.graphml", + "docs/static/images/architecture.png":"load/projects/pandora/docs/static/images/architecture.png", + "docs/static/images/http_100kb_net.png":"load/projects/pandora/docs/static/images/http_100kb_net.png", + "docs/static/images/http_connection_close_td.png":"load/projects/pandora/docs/static/images/http_connection_close_td.png", + "docs/static/images/http_delay_10s_instances.png":"load/projects/pandora/docs/static/images/http_delay_10s_instances.png", + "docs/static/images/http_delay_10s_td.png":"load/projects/pandora/docs/static/images/http_delay_10s_td.png", + "docs/static/images/http_keep_alive_td.png":"load/projects/pandora/docs/static/images/http_keep_alive_td.png", + "docs/static/images/http_srv_fail_q.png":"load/projects/pandora/docs/static/images/http_srv_fail_q.png", + "docs/static/images/scn_cases.png":"load/projects/pandora/docs/static/images/scn_cases.png", "examples/connect.yaml":"load/projects/pandora/examples/connect.yaml", "examples/custom_pandora/custom.yaml":"load/projects/pandora/examples/custom_pandora/custom.yaml", "examples/custom_pandora/custom_main.go":"load/projects/pandora/examples/custom_pandora/custom_main.go", diff --git a/docs/.cspell.yml b/docs/.cspell.yml new file mode 100644 index 000000000..27c4aa188 --- /dev/null +++ b/docs/.cspell.yml @@ -0,0 +1,9 @@ +# cSpell:ignore textlintrc +# For settings, see +# https://www.streetsidesoftware.com/vscode-spell-checker/docs/configuration/ +version: '0.2' +caseSensitive: true +words: + - Docsy + - Yandex + - Pandora diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..40b67f41a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +/public +resources/ +node_modules/ +package-lock.json +.hugo_build.lock \ No newline at end of file diff --git a/docs/.nvmrc b/docs/.nvmrc new file mode 100644 index 000000000..b009dfb9d --- /dev/null +++ b/docs/.nvmrc @@ -0,0 +1 @@ +lts/* diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..481ce6741 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,184 @@ +# Docsy Example + +[Docsy][] is a [Hugo theme module][] for technical documentation sites, providing easy +site navigation, structure, and more. This **Docsy Example Project** uses the Docsy +theme component as a hugo module and provides a skeleton documentation structure for you to use. +You can clone/copy this project and edit it with your own content, or use it as an example. + +In this project, the Docsy theme is pulled in as a Hugo module, together with +its dependencies: + +```console +$ hugo mod graph +... +``` + +For Docsy documentation, see [Docsy user guide][]. + +This Docsy Example Project is hosted on [Netlify][] at [example.docsy.dev][]. +You can view deploy logs from the [deploy section of the project's Netlify +dashboard][deploys], or this [alternate dashboard][]. + +This is not an officially supported Google product. This project is currently maintained. + +## Using the Docsy Example Project as a template + +A simple way to get started is to use this project as a template, which gives you a site project that is set up and ready to use. To do this: + +1. Use the dropdown for switching branches/tags to change to the **latest** released tag. + +2. Click **Use this template**. + +3. Select a name for your new project and click **Create repository from template**. + +4. Make your own local working copy of your new repo using git clone, replacing https://github.com/me/example.git with your repo’s web URL: + +```bash +git clone --depth 1 https://github.com/me/example.git +``` + +You can now edit your own versions of the site’s source files. + +If you want to do SCSS edits and want to publish these, you need to install `PostCSS` + +```bash +npm install +``` + +## Running the website locally + +Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io). +You can find out more about how to install Hugo for your environment in our +[Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide. + +Once you've made your working copy of the site repo, from the repo root folder, run: + +```bash +hugo server +``` + +## Running a container locally + +You can run docsy-example inside a [Docker](https://docs.docker.com/) +container, the container runs with a volume bound to the `docsy-example` +folder. This approach doesn't require you to install any dependencies other +than [Docker Desktop](https://www.docker.com/products/docker-desktop) on +Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/) +on Linux. + +1. Build the docker image + + ```bash + docker-compose build + ``` + +1. Run the built image + + ```bash + docker-compose up + ``` + + > NOTE: You can run both commands at once with `docker-compose up --build`. + +1. Verify that the service is working. + + Open your web browser and type `http://localhost:1313` in your navigation bar, + This opens a local instance of the docsy-example homepage. You can now make + changes to the docsy example and those changes will immediately show up in your + browser after you save. + +### Cleanup + +To stop Docker Compose, on your terminal window, press **Ctrl + C**. + +To remove the produced images run: + +```bash +docker-compose rm +``` +For more information see the [Docker Compose documentation][]. + +## Using a local Docsy clone + +Make sure your installed go version is `1.18` or higher. + +Clone the latest version of the docsy theme into the parent folder of your project. The newly created repo should now reside in a sibling folder of your site's root folder. + +```shell +cd root-of-your-site +git clone --branch v0.7.2 https://github.com/google/docsy.git ../docsy +``` + +Now run: + +```shell +HUGO_MODULE_WORKSPACE=docsy.work hugo server --ignoreVendorPaths "**" +``` + +or, when using npm, prepend `local` to the script you want to invoke, e.g.: + +```shell +npm run local serve +``` + +By using the `HUGO_MODULE_WORKSPACE` directive (either directly or via prefix `local` when using npm), the server now watches all files and directories inside the sibling directory `../docsy` , too. Any changes inside the local `docsy` theme clone are now immediately picked up (hot reload), you can instantly see the effect of your local edits. + +In the command above, we used the environment variable `HUGO_MODULE_WORKSPACE` to tell hugo about the local workspace file `docsy.work`. Alternatively, you can declare the workspace file inside your settings file `hugo.toml`: + +```toml +[module] + workspace = "docsy.work" +``` + +Your project's `hugo.toml` file already contains these lines, the directive for workspace assignment is commented out, however. Remove the two trailing comment characters '//' so that this line takes effect. + +## Troubleshooting + +As you run the website locally, you may run into the following error: + +```console +$ hugo server +WARN 2023/06/27 16:59:06 Module "project" is not compatible with this Hugo version; run "hugo mod graph" for more information. +Start building sites … +hugo v0.101.0-466fa43c16709b4483689930a4f9ac8add5c9f66+extended windows/amd64 BuildDate=2022-06-16T07:09:16Z VendorInfo=gohugoio +Error: Error building site: "C:\Users\foo\path\to\docsy-example\content\en\_index.md:5:1": failed to extract shortcode: template for shortcode "blocks/cover" not found +Built in 27 ms +``` + +This error occurs if you are running an outdated version of Hugo. As of docsy theme version `v0.7.0`, hugo version `0.110.0` or higher is required. +See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo. + +Or you may be confronted with the following error: + +```console +$ hugo server + +INFO 2021/01/21 21:07:55 Using config file: +Building sites … INFO 2021/01/21 21:07:55 syncing static files to / +Built in 288 ms +Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache +``` + +This error occurs if you have not installed the extended version of Hugo. +See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo. + +Or you may encounter the following error: + +```console +$ hugo server + +Error: failed to download modules: binary with name "go" not found +``` + +This error occurs if you have not installed the `go` programming language on your system. +See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`. + + +[alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys +[deploys]: https://app.netlify.com/sites/docsy-example/deploys +[Docsy user guide]: https://docsy.dev/docs +[Docsy]: https://github.com/google/docsy +[example.docsy.dev]: https://example.docsy.dev +[Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme +[Netlify]: https://netlify.com +[Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/ diff --git a/docs/assets/scss/_variables_project.scss b/docs/assets/scss/_variables_project.scss new file mode 100644 index 000000000..256902739 --- /dev/null +++ b/docs/assets/scss/_variables_project.scss @@ -0,0 +1,6 @@ +/* + +Add styles or override variables from the theme here. + +*/ + diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 000000000..9070e384f --- /dev/null +++ b/docs/config.yaml @@ -0,0 +1,15 @@ +# THIS IS A TEST CONFIG ONLY! +# FOR THE CONFIGURATION OF YOUR SITE USE hugo.yaml. +# +# As of Docsy 0.7.0, Hugo 0.110.0 or later must be used. +# +# The sole purpose of this config file is to detect Hugo-module builds that use +# an older version of Hugo. +# +# DO NOT add any config parameters to this file. You can safely delete this file +# if your project is using the required Hugo version. + +module: + hugoVersion: + extended: true + min: 0.110.0 diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md new file mode 100755 index 000000000..1a6528cef --- /dev/null +++ b/docs/content/en/_index.md @@ -0,0 +1,7 @@ +--- +title: Documentation +linkTitle: Docs +--- + +Pandora is a high-performance load generator in Go language. It has built-in HTTP(S) and HTTP/2 support and you can +write your own load scenarios in Go, compiling them just before your test. diff --git a/docs/eng/architecture.md b/docs/content/en/architecture.md similarity index 88% rename from docs/eng/architecture.md rename to docs/content/en/architecture.md index 1f0bf1206..2224c0e55 100644 --- a/docs/eng/architecture.md +++ b/docs/content/en/architecture.md @@ -1,16 +1,10 @@ -[Home](../index.md) - --- - -# Architectural overview - -- [Architectural scheme](#architectural-scheme) -- [Component types](#component-types) - - [Ammo Provider](#ammo-provider) - - [Instances Pool](#instances-pool) - - [Scheduler](#scheduler) - - [Instances and Guns](#instances-and-guns) - - [Aggregator](#aggregator) +title: Architectural overview +description: Pandora is a set of components talking to each other through Go channels. There are different types of components. +categories: [Get started] +tags: [architecture] +weight: 14 +--- ## Architectural scheme @@ -64,7 +58,3 @@ a request to your service and measures the parameters (time, error codes, etc.) ### Aggregator Aggregator collects measured samples and saves them somewhere. - ---- - -[Home](../index.md) \ No newline at end of file diff --git a/docs/content/en/best-practices/_index.md b/docs/content/en/best-practices/_index.md new file mode 100755 index 000000000..4a2ca4449 --- /dev/null +++ b/docs/content/en/best-practices/_index.md @@ -0,0 +1,6 @@ +--- +title: Best practices +description: +categories: [Best practices] +weight: 6 +--- \ No newline at end of file diff --git a/docs/eng/best_practices/discard-overflow.md b/docs/content/en/best-practices/discard-overflow.md similarity index 93% rename from docs/eng/best_practices/discard-overflow.md rename to docs/content/en/best-practices/discard-overflow.md index a8ff89aee..2aaa5ebe1 100644 --- a/docs/eng/best_practices/discard-overflow.md +++ b/docs/content/en/best-practices/discard-overflow.md @@ -1,8 +1,10 @@ -[Home](../../index.md) - --- - -# Discard Overflow +title: Discard overflow +description: The setting includes the behavior of discarding overdue requests +categories: [Best practices] +tags: [best_practices, discard_overflow] +weight: 1 +--- When you specify a [load profile](../load-profile.md), the generator calculates the order and timing of requests. This can be referred to as the schedule of requests execution. Pandora's scheduler is responsible for this. It receives @@ -43,7 +45,3 @@ To avoid such situations, you can: - Increase the number of instances. - Decrease the load profile. - Optimize the server being tested to reduce response time. - ---- - -[Home](../../index.md) diff --git a/docs/eng/best_practices/rps-per-instance.md b/docs/content/en/best-practices/rps-per-instance.md similarity index 88% rename from docs/eng/best_practices/rps-per-instance.md rename to docs/content/en/best-practices/rps-per-instance.md index 575d8ac1b..f3d79e29d 100644 --- a/docs/eng/best_practices/rps-per-instance.md +++ b/docs/content/en/best-practices/rps-per-instance.md @@ -1,8 +1,10 @@ -[Home](../../index.md) - --- - -# RPS per instance +title: RPS per instance +description: The setting allows you to change the rule for calculating the load profile +categories: [Best practices] +tags: [best_practices, discard_overflow] +weight: 2 +--- Usually in tests, when we increase the speed of requests submitted to the target service by specifying the `line`, `const`, `step` scheme in the rps section, then in the `startup` section we specify the `once` scheme, because we want all instances to be available from the very beginning of the test in order to generate the load we need. diff --git a/docs/eng/best_practices/shared-client.md b/docs/content/en/best-practices/shared-client.md similarity index 89% rename from docs/eng/best_practices/shared-client.md rename to docs/content/en/best-practices/shared-client.md index 4e4ab842c..339cfdb2b 100644 --- a/docs/eng/best_practices/shared-client.md +++ b/docs/content/en/best-practices/shared-client.md @@ -1,8 +1,10 @@ -[Home](../../index.md) - --- - -# Use shared client +title: Use shared client +description: The setting allows you to reduce the number of open connections to the server +categories: [Best practices] +tags: [best_practices, shared_client] +weight: 3 +--- ## General principle @@ -31,7 +33,3 @@ A single client uses multiple connections and can create additional connections But under heavy loads there may be a situation when the client does not have time to create connections. You can increase the speed of connection creation by a common client by increasing the `shared-client.client-number` parameter. By default `shared-client.client-number=1`. - ---- - -[Home](../../index.md) diff --git a/docs/eng/config.md b/docs/content/en/config.md similarity index 91% rename from docs/eng/config.md rename to docs/content/en/config.md index ef5c5a69e..576ab95ec 100644 --- a/docs/eng/config.md +++ b/docs/content/en/config.md @@ -1,12 +1,10 @@ -[Home](../index.md) - --- - -# Configuration - -- [Basic configuration](#basic-configuration) -- [Monitoring and Logging](#monitoring-and-logging) -- [Variables from env and files](#variables-from-env-and-files) +title: Configuration +description: Pandora supports config files in `YAML` format. +categories: [Get started] +tags: [config] +weight: 2 +--- ## Basic configuration @@ -88,7 +86,3 @@ pools: ``` You can use variables not only in the header section but also in other configuration fields. - ---- - -[Home](../index.md) diff --git a/docs/eng/custom.md b/docs/content/en/custom.md similarity index 99% rename from docs/eng/custom.md rename to docs/content/en/custom.md index f8989ef88..506111c43 100644 --- a/docs/eng/custom.md +++ b/docs/content/en/custom.md @@ -1,8 +1,10 @@ -[Home](../index.md) - --- - -# Custom guns +title: Custom guns +description: Custom guns +categories: [Generator] +tags: [generator] +weight: 11 +--- - [Basic tutorial](#basic-tutorial) - [gRPC](#grpc) @@ -49,7 +51,7 @@ pools: And create ammofile `./json.ammo`: -```yaml +```json {"tag": "/MyCase1", "Param1": "146837693,146837692,146837691"} {"tag": "/MyCase2", "Param2": "555", "Param1": "500002"} ``` @@ -449,7 +451,3 @@ func main() { cli.Run() } ``` - ---- - -[Home](../index.md) \ No newline at end of file diff --git a/docs/eng/grpc-generator.md b/docs/content/en/grpc-generator.md similarity index 95% rename from docs/eng/grpc-generator.md rename to docs/content/en/grpc-generator.md index 373156b66..3b6abd450 100644 --- a/docs/eng/grpc-generator.md +++ b/docs/content/en/grpc-generator.md @@ -1,8 +1,10 @@ -[Home](index.md) - --- - -# gRPC generator +title: gRPC generator +description: Configure gRPC generator +categories: [Generator] +tags: [generator, grpc] +weight: 8 +--- Full gRPC generator config @@ -60,7 +62,3 @@ But to unify reports it converts them into HTTP codes. - Best practices - [RPS per instance](best_practices/rps-per-instance.md) - [Shared client](best_practices/shared-client.md) - ---- - -[Home](index.md) diff --git a/docs/eng/http-generator.md b/docs/content/en/http-generator.md similarity index 96% rename from docs/eng/http-generator.md rename to docs/content/en/http-generator.md index fd64ff4e3..9208c1791 100644 --- a/docs/eng/http-generator.md +++ b/docs/content/en/http-generator.md @@ -1,8 +1,10 @@ -[Home](../index.md) - --- - -# HTTP generator +title: HTTP generator +description: Configure HTTP generator +categories: [Generator] +tags: [generator, http] +weight: 9 +--- Full http (http2) generator config @@ -47,7 +49,3 @@ gun: - Best practices - [RPS per instance](best_practices/rps-per-instance.md) - [Shared client](best_practices/shared-client.md) - ---- - -[Home](../index.md) diff --git a/docs/eng/install.md b/docs/content/en/install.md similarity index 73% rename from docs/eng/install.md rename to docs/content/en/install.md index 042161f9d..68dfc984c 100644 --- a/docs/eng/install.md +++ b/docs/content/en/install.md @@ -1,8 +1,10 @@ -[Home](../index.md) - --- - -# Installation +title: Installation +description: How install Yandex Pandora +categories: [Get started] +tags: [install] +weight: 1 +--- [Download](https://github.com/yandex/pandora/releases) binary release or build from source. @@ -20,6 +22,3 @@ You can also cross-compile for other arch/os: GOOS=linux GOARCH=amd64 go build ``` ---- - -[Home](../index.md) diff --git a/docs/eng/load-profile.md b/docs/content/en/load-profile.md similarity index 90% rename from docs/eng/load-profile.md rename to docs/content/en/load-profile.md index bc89d1b16..851dd48ec 100644 --- a/docs/eng/load-profile.md +++ b/docs/content/en/load-profile.md @@ -1,8 +1,10 @@ -[Home](../index.md) - --- - -# Load profile +title: Load profile +description: It sets how the load will be changed and maintained. +categories: [Load profile] +tags: [load_profile] +weight: 4 +--- To determine what load to create on the server, use a load profile. It sets how the load will be changed and maintained. @@ -82,7 +84,3 @@ rps: type: unlimited duration: 30s ``` - ---- - -[Home](../index.md) diff --git a/docs/eng/performance.md b/docs/content/en/performance.md similarity index 93% rename from docs/eng/performance.md rename to docs/content/en/performance.md index 2d7894199..fb219b835 100644 --- a/docs/eng/performance.md +++ b/docs/content/en/performance.md @@ -1,11 +1,10 @@ -[Home](../index.md) - --- - -# Pandora's performance - -- [HTTP requests to nginx](#http-requests-to-nginx) -- [Custom scenarios](#custom-scenarios) +title: Pandora performance +description: Some performance tests for the gun itself +categories: [Best practise] +tags: [config, test, performance] +weight: 13 +--- [Alexander Ivanov](mailto:ival.net@yandex.ru) made some performance tests for the gun itself. Here are the results. @@ -99,7 +98,3 @@ to do this. * **Some scenario steps with big JSON bodies** 35k RPS. OK. ![scenario steps](../images/scn_cases.png) - - --- - -[Home](../index.md) diff --git a/docs/eng/providers.md b/docs/content/en/providers.md similarity index 93% rename from docs/eng/providers.md rename to docs/content/en/providers.md index 6d9da46e6..980b85275 100644 --- a/docs/eng/providers.md +++ b/docs/content/en/providers.md @@ -1,17 +1,10 @@ -[Home](../index.md) - --- - -# HTTP Ammo providers - -- [Test data](#test-data) - - [http/json](#httpjson) - - [raw (request-style)](#raw-request-style) - - [uri-style](#uri-style) -- [Features](#features) - - [Ammo filters](#ammo-filters) - - [HTTP Ammo middlewares](#http-ammo-middlewares) - - [HTTP Ammo preloaded](#http-ammo-preloaded) +title: HTTP Ammo providers +description: HTTP Ammo provider is a source of test data - it makes ammo object +categories: [Provider] +tags: [provider, http] +weight: 6 +--- HTTP Ammo provider is a source of test data: it makes ammo object. @@ -231,7 +224,3 @@ pools: ... preload: true ``` - ---- - -[Home](../index.md) diff --git a/docs/eng/scenario-grpc-generator.md b/docs/content/en/scenario-grpc-generator.md similarity index 85% rename from docs/eng/scenario-grpc-generator.md rename to docs/content/en/scenario-grpc-generator.md index 3e222972d..3c416b503 100644 --- a/docs/eng/scenario-grpc-generator.md +++ b/docs/content/en/scenario-grpc-generator.md @@ -1,29 +1,10 @@ -[Home](../index.md) - --- - -# Scenario generator / gRPC - -- [Configuration](#configuration) - - [Generator](#generator) - - [Provider](#provider) -- [Description of the scenario format](#description-of-the-scenario-format) - - [General principle](#general-principle) - - [HCL example](#hcl-example) - - [YAML example](#yaml-example) - - [Locals](#locals) -- [Features](#features) - - [Calls](#calls) - - [Templater](#templater) - - [Variable names in templates](#variable-names-in-templates) - - [Functions in templates](#functions-in-templates) - - [Preprocessors](#preprocessors) - - [prepare](#prepare) - - [Postprocessors](#postprocessors) - - [assert/response](#assertresponse) - - [Scenarios](#scenarios) - - [Sources](#sources) -- [References](#references) +title: Scenario generator / gRPC +description: Scenario generator / gRPC +categories: [generator] +tags: [scenario, generator, grpc] +weight: 10 +--- ## Configuration @@ -70,7 +51,7 @@ Supports file extensions ## Description of the scenario format -Supports formats +Support formats - hcl - yaml @@ -318,10 +299,4 @@ Follow - [Variable sources](scenario/variable_source.md) # References - [gRPC generator](grpc-generator.md) -- Best practices - - [RPS per instance](best_practices/rps-per-instance.md) - - [Shared client](best_practices/shared-client.md) - ---- - -[Home](../index.md) +- [Практики использования](best-practices) \ No newline at end of file diff --git a/docs/eng/scenario-http-generator.md b/docs/content/en/scenario-http-generator.md similarity index 88% rename from docs/eng/scenario-http-generator.md rename to docs/content/en/scenario-http-generator.md index 984f66744..4ce4e3671 100644 --- a/docs/eng/scenario-http-generator.md +++ b/docs/content/en/scenario-http-generator.md @@ -1,31 +1,10 @@ -[Home](../index.md) - --- - -# Scenario generator / HTTP - -- [Configuration](#configuration) - - [Generator](#generator) - - [Provider](#provider) -- [Description of the scenario format](#description-of-the-scenario-format) - - [General principle](#general-principle) - - [HCL example](#hcl-example) - - [YAML example](#yaml-example) - - [Locals](#locals) -- [Features](#features) - - [Requests](#requests) - - [Templater](#templater) - - [Variable names in templates](#variable-names-in-templates) - - [Functions in templates](#functions-in-templates) - - [Preprocessors](#preprocessors) - - [Postprocessors](#postprocessors) - - [var/jsonpath](#varjsonpath) - - [var/xpath](#varxpath) - - [var/header](#varheader) - - [assert/response](#assertresponse) - - [Scenarios](#scenarios) - - [Sources](#sources) -- [References](#references) +title: Scenario generator / HTTP +description: Scenario generator / HTTP +categories: [generator] +tags: [scenario, generator, http] +weight: 9 +--- ## Configuration @@ -482,11 +461,4 @@ Follow - [Variable sources](scenario/variable_source.md) # References - [HTTP generator](http-generator.md) -- Best practices - - [RPS per instance](best_practices/rps-per-instance.md) - - [Shared client](best_practices/shared-client.md) - - ---- - -[Home](../index.md) +- [Практики использования](best-practices) diff --git a/docs/content/en/scenario/_index.md b/docs/content/en/scenario/_index.md new file mode 100644 index 000000000..35fefcb41 --- /dev/null +++ b/docs/content/en/scenario/_index.md @@ -0,0 +1,6 @@ +--- +title: Scenario +linkTitle: Scenario +description: Common scenario settings +weight: 11 +--- diff --git a/docs/eng/scenario/functions.md b/docs/content/en/scenario/functions.md similarity index 97% rename from docs/eng/scenario/functions.md rename to docs/content/en/scenario/functions.md index 357166ac2..e3a142db7 100644 --- a/docs/eng/scenario/functions.md +++ b/docs/content/en/scenario/functions.md @@ -1,8 +1,10 @@ -[Home](../../index.md) - --- - -# Randomization Functions +title: Randomization functions +description: You can use functions to generate random values +categories: [Scenario] +tags: [scenario, function] +weight: 3 +--- You can use functions to generate random values: - randInt @@ -162,7 +164,3 @@ You can use follow function - [Scenario generator / HTTP](../scenario-http-generator.md) - [Scenario generator / gRPC](../scenario-grpc-generator.md) - ---- - -[Home](../../index.md) diff --git a/docs/eng/scenario/locals.md b/docs/content/en/scenario/locals.md similarity index 95% rename from docs/eng/scenario/locals.md rename to docs/content/en/scenario/locals.md index bbc9f82a3..4ced244e0 100644 --- a/docs/eng/scenario/locals.md +++ b/docs/content/en/scenario/locals.md @@ -1,8 +1,10 @@ -[Home](../../index.md) - --- - -# Locals +title: Locals +description: locals block in hcl +categories: [Scenario] +tags: [scenario, local] +weight: 2 +--- Foreword: @@ -94,7 +96,3 @@ requests: - [Scenario generator / HTTP](../scenario-http-generator.md) - [Scenario generator / gRPC](../scenario-grpc-generator.md) - ---- - -[Home](../../index.md) diff --git a/docs/eng/scenario/variable_source.md b/docs/content/en/scenario/variable_source.md similarity index 94% rename from docs/eng/scenario/variable_source.md rename to docs/content/en/scenario/variable_source.md index 2e90a20d6..129dd2674 100644 --- a/docs/eng/scenario/variable_source.md +++ b/docs/content/en/scenario/variable_source.md @@ -1,5 +1,9 @@ -[Home](../../index.md) - +--- +title: Variable sources +description: variable_source block in scenarios +categories: [Scenario] +tags: [scenario, source, variable] +weight: 1 --- # Variable sources diff --git a/docs/content/en/search.md b/docs/content/en/search.md new file mode 100644 index 000000000..394feea5f --- /dev/null +++ b/docs/content/en/search.md @@ -0,0 +1,4 @@ +--- +title: Search Results +layout: search +--- diff --git a/docs/eng/startup.md b/docs/content/en/startup.md similarity index 90% rename from docs/eng/startup.md rename to docs/content/en/startup.md index 5660cc812..7d40782ab 100644 --- a/docs/eng/startup.md +++ b/docs/content/en/startup.md @@ -1,8 +1,10 @@ -[Home](index.md) - --- - -# Instance startup profile +title: Instance startup profile +description: How many instances you need, and how quickly they will be available to you +categories: [Startup] +tags: [startup] +weight: 5 +--- You can control the profile of instance starts. diff --git a/docs/eng/tutorial.md b/docs/content/en/tutorial.md similarity index 96% rename from docs/eng/tutorial.md rename to docs/content/en/tutorial.md index b7b483377..433c6d448 100644 --- a/docs/eng/tutorial.md +++ b/docs/content/en/tutorial.md @@ -1,8 +1,8 @@ -[Home](../index.md) - --- - -# Your first test +title: Your first test +description: +weight: 3 +--- You can use Pandora alone or use it with [Yandex.Tank](https://yandextank.readthedocs.io/en/latest/core_and_modules.html#pandora) as a test runner and [Overload](https://overload.yandex.net) as a result viewer. In the second case Pandora's configuration is the same, but you will embed it into Yandex.Tank's config. @@ -44,7 +44,3 @@ pandora load.yaml ``` The results are in `phout.log`. Use [Yandex.Tank](https://yandextank.readthedocs.io/en/latest/core_and_modules.html#pandora) and [Overload](https://overload.yandex.net) to plot them. - ---- - -[Home](../index.md) diff --git a/docs/content/ru/_index.md b/docs/content/ru/_index.md new file mode 100755 index 000000000..4fae06951 --- /dev/null +++ b/docs/content/ru/_index.md @@ -0,0 +1,7 @@ +--- +title: Документация Yandex Pandora +linkTitle: Документация +--- + +Pandora - это высокопроизводительный генератор нагрузки на языке Go. Он имеет встроенную поддержку HTTP(S) и HTTP/2, +и вы можете писать собственные сценарии нагрузки на языке Go, компилируя их непосредственно перед тестированием. diff --git a/docs/rus/architecture.md b/docs/content/ru/architecture.md similarity index 85% rename from docs/rus/architecture.md rename to docs/content/ru/architecture.md index 76139543d..6a695801f 100644 --- a/docs/rus/architecture.md +++ b/docs/content/ru/architecture.md @@ -1,23 +1,17 @@ -[К содержанию](index.md) - --- - -# Архитектура - -- [Схема](#схема) -- [Типы компонентов](#типы-компонентов) - - [Provider](#provider) - - [Instances Pool](#instances-pool) - - [Scheduler](#scheduler) - - [Instances and Guns](#instances-and-guns) - - [Aggregator](#aggregator) +title: Архитектура +description: Pandora - это набор компонентов, взаимодействующих друг с другом с помощью Go каналов +categories: [Get started] +tags: [architecture] +weight: 14 +--- ## Схема -Код схемы доступен [здесь](../images/architecture.graphml). +Код схемы доступен [здесь](../../images/architecture.graphml). Его можно открыть и редактировать в редакторе [YeD](https://www.yworks.com/en/products/yfiles/yed/). -![architectural scheme](../images/architecture.png) +![architectural scheme](../../images/architecture.png) Pandora - это набор компонентов, взаимодействующих друг с другом с помощью Go каналов. @@ -67,7 +61,3 @@ a request to your service and measures the parameters (time, error codes, etc.) ### Aggregator Aggregator collects measured samples and saves them somewhere. - ---- - -[К содержанию](index.md) diff --git a/docs/content/ru/best-practices/_index.md b/docs/content/ru/best-practices/_index.md new file mode 100755 index 000000000..df0ccdd90 --- /dev/null +++ b/docs/content/ru/best-practices/_index.md @@ -0,0 +1,6 @@ +--- +title: Лучшие практики +description: +categories: [Best practices] +weight: 6 +--- \ No newline at end of file diff --git a/docs/rus/best_practices/discard-overflow.md b/docs/content/ru/best-practices/discard-overflow.md similarity index 90% rename from docs/rus/best_practices/discard-overflow.md rename to docs/content/ru/best-practices/discard-overflow.md index f349d3976..90920b6bd 100644 --- a/docs/rus/best_practices/discard-overflow.md +++ b/docs/content/ru/best-practices/discard-overflow.md @@ -1,12 +1,14 @@ -[Домой](../index.md) - --- - -# Discard overflow +title: Discard overflow +description: Настройка включает поведение отбрасывания запоздавших запросов +categories: [Best practices] +tags: [best_practices, discard_overflow] +weight: 1 +--- Когда вы указываете [профиль нагрузки](../load-profile.md) генератор рассчитывает порядок и время выполнения запросов. Можно назвать это расписанием выполнения запросов. За это отвечает планировщик Пандоры. Он получает запросы от -провайдера и по этому рассписанию передает инстансам. А каждый инстанс выполняет запросы последовательно. +провайдера и по этому расписанию передает инстансам. А каждый инстанс выполняет запросы последовательно. Может возникнуть ситуация, когда планировщик считает, что наступило время выполнить следующий запрос, но все инстансы заняты ожиданием выполнения своего текущего запроса. В этом случае планировщик может поступать одним из 2-х способов. @@ -22,7 +24,7 @@ и количества инстансов. 2. `discard_overflow: true` - строгое следование генератором расписания запросов. Запросы, не уложившиеся в расписание, отбрасываются. Время выполнения теста предопределено. Запросы, которые не укладываются в расписание, - помечаются неудавшимися (ошибка net `777`, а так же добавляется tag:discarded). Пандора считает, что тест не уложился + помечаются неудавшимися (ошибка net `777`, а так же добавляется tag:discarded). Пандора считает, что тест не уложился в расписание, если время запроса отстало на 2 сек. То есть используется 2 секундное скользящее окно. По-умолчанию, начиная с версии pandora@0.5.24 настройка `discard_overflow: true` @@ -42,7 +44,3 @@ - увеличить кол-во инстансов - уменьшить профиль нагрузки - оптимизировать нагружаемый сервис, для уменьшения времени ответа - ---- - -[Домой](../index.md) diff --git a/docs/rus/best_practices/rps-per-instance.md b/docs/content/ru/best-practices/rps-per-instance.md similarity index 78% rename from docs/rus/best_practices/rps-per-instance.md rename to docs/content/ru/best-practices/rps-per-instance.md index 1e53e985b..c1d736dd2 100644 --- a/docs/rus/best_practices/rps-per-instance.md +++ b/docs/content/ru/best-practices/rps-per-instance.md @@ -1,8 +1,10 @@ -[Домой](../index.md) - --- - -# RPS на инстанс +title: RPS на инстанс +description: Настройка позволяет изменить правило расчета профиля нагрузки +categories: [Best practices] +tags: [best_practices, rps] +weight: 2 +--- Обычно в тестах, когда мы увеличиваем скорость запросов, подаваемых на тестируемый севис, указывая схему `line`, `const`, `step` в секции rps, то в секции `startup` мы указываем схему `once`, т.к. хотим, чтобы с самого начала теста нам были доступны все инстансы для того, чтобы сгенерить нужную нам нагрузку. @@ -10,7 +12,7 @@ В тестах со сценарной нагрузкой, когда у нас каждый инстанс описыает поведение пользователя, то в секции `startup` можно указывать плавный рост количества пользователей, например схемой `instance_step`, увеличивая ступенчато их кол-во, или `const`, увеличивая пользователей с постоянной скоростью. Для этого можно использовать настройку пула инстансов `rps-per-instance`. Она полезна для сценарного генератора, когда мы хотим ограничить скорость каждого пользователя в rps. -Например укажем `const` и включим `rps-per-instance`, то потом увеличивая пользователей через `instance_step`, мы имитируем реальную пользовательскую нагрузку. +Например, укажем `const` и включим `rps-per-instance`, то потом увеличивая пользователей через `instance_step`, мы имитируем реальную пользовательскую нагрузку. Пример: @@ -41,7 +43,3 @@ pools: log: level: error ``` - ---- - -[Домой](../index.md) diff --git a/docs/rus/best_practices/shared-client.md b/docs/content/ru/best-practices/shared-client.md similarity index 82% rename from docs/rus/best_practices/shared-client.md rename to docs/content/ru/best-practices/shared-client.md index 186012d38..aed924d76 100644 --- a/docs/rus/best_practices/shared-client.md +++ b/docs/content/ru/best-practices/shared-client.md @@ -1,26 +1,29 @@ -[Домой](../index.md) - --- -# Использовать общий транспорт +title: Использовать общий транспорт +description: Настройка позволяет уменьшить количество открытых соединений с сервером +categories: [Best practices] +tags: [best_practices, shared_client] +weight: 3 +--- ## Общий принцип ### Транспортный клиент -По умолчанию, компоненты Pandora при создании нового Инстанса автоматически назначают ему транспортного клиента, -например, для http, grpc или tcp. Когда Инстанс запускается, он открывает соединение, например, tcp соединение. -Обычно, клиенты могут использовать несколько соединений одновременно, но в случае с Pandora, +По умолчанию, компоненты Pandora при создании нового Инстанса автоматически назначают ему транспортного клиента, +например, для http, grpc или tcp. Когда Инстанс запускается, он открывает соединение, например, tcp соединение. +Обычно, клиенты могут использовать несколько соединений одновременно, но в случае с Pandora, каждый Инстанс открывает только одно соединение, так как Инстанс выполняет запросы один за другим. -Стоит заметить, что создание соединения не означает, что запросы будут идти через это соединение. Почему? +Стоит заметить, что создание соединения не означает, что запросы будут идти через это соединение. Почему? В настройках теста можно указать большое кол-во инстансов и маленькое кол-во RPS. -Провайдер Пандора генерирует запросы с частотой указаной в настройках RPS и передает на случайный инстанс, чтобы -инстанс выполнил этот запрос. +Провайдер Пандора генерирует запросы с частотой указаной в настройках RPS и передает на случайный инстанс, чтобы +инстанс выполнил этот запрос. ## `shared-client` -В настройках генераторов [http](../http-generator.md) и [grpc](../grpc-generator.md) можно указать параметр `shared-client.enabled=true`. -Если включить данную настройку, то все инстансы будут использовать общий транспортный клиент и каждый не будет +В настройках генераторов [http](../http-generator.md) и [grpc](../grpc-generator.md) можно указать параметр `shared-client.enabled=true`. +Если включить данную настройку, то все инстансы будут использовать общий транспортный клиент и каждый не будет создавать собственный. ## `shared-client.client-number` @@ -31,7 +34,3 @@ Но при больших нагрузках может возникнуть ситуация, когда клиент не успевает создать соединения. Можно увеличить, скорость создания соединений общим клиентом, увеличив параметро `shared-client.client-number`. По умолчанию `shared-client.client-number=1` - ---- - -[Домой](../index.md) diff --git a/docs/rus/config.md b/docs/content/ru/config.md similarity index 90% rename from docs/rus/config.md rename to docs/content/ru/config.md index 7b9ad9c3f..7089fdbaf 100644 --- a/docs/rus/config.md +++ b/docs/content/ru/config.md @@ -1,12 +1,10 @@ -[К содержанию](index.md) - --- - -# Конфигурация - -- [Основная конфигурация](#basic-configuration) -- [Мониторинг и логирование](#monitoring-and-logging) -- [Переменные из переменных окружения и файлов](#variables-from-env-and-files) +title: Конфигурация +description: Pandora поддерживает файлы конфигурации в формате `YAML` +categories: [Get started] +tags: [config] +weight: 2 +--- ## Основная конфигурация @@ -87,7 +85,3 @@ pools: ``` Переменные можно использовать не только в секции `headers`, но и в любых других полях конфигурации. - ---- - -[К содержанию](index.md) diff --git a/docs/content/ru/custom.md b/docs/content/ru/custom.md new file mode 100644 index 000000000..88c0d6c66 --- /dev/null +++ b/docs/content/ru/custom.md @@ -0,0 +1,449 @@ +--- +title: Custom guns +description: Custom guns +categories: [Generator] +tags: [generator] +weight: 11 +--- + +## Basic tutorial + +You can create you own Golang-based gun with _pandora_. + +There is an example of custom gun shooting via gRPC. + +We create a new gun and define `shoot` method for it w/ our test logic. + +You can find examples of custom guns' code below: +- [gRPC](#gRPC) +- [Websockets](#Websockets) + +Now it's time to compile our gun. Install deps and compile your custom gun file (`go build my_custom_gun.go`). + +After that step you'll get `my_custom_gun` binary file, it is compiled pandora with your custom gun inside. + +Now its time to create `load.yaml`: + +```yaml +pools: + - id: HTTP pool + gun: + type: my_custom_gun_name # custom gun name (specified at `register.Gun("my_custom_gun_name", ...`) + target: "your_grpc_host:your_grpc_port" + ammo: + type: custom_provider + source: + type: file + path: ./json.ammo + result: + type: phout + destination: ./phout.log + rps: { duration: 30s, type: line, from: 1, to: 2 } + startup: + type: once + times: 10 + log: +``` + +And create ammofile `./json.ammo`: + +```json +{"tag": "/MyCase1", "Param1": "146837693,146837692,146837691"} +{"tag": "/MyCase2", "Param2": "555", "Param1": "500002"} +``` + + +We are ready to shoot. Try it. + + +## gRPC + +```go +// create a package +package main + +// import some pandora stuff +// and stuff you need for your scenario +// and protobuf contracts for your grpc service + +import ( + "log" + "context" + "strconv" + "strings" + "time" + + "github.com/golang/protobuf/ptypes/timestamp" + "github.com/satori/go.uuid" + "github.com/spf13/afero" + "google.golang.org/grpc" + pb "my_package/my_protobuf_contracts" + + "github.com/yandex/pandora/cli" + "github.com/yandex/pandora/components/phttp/import" + "github.com/yandex/pandora/core" + "github.com/yandex/pandora/core/aggregator/netsample" + "github.com/yandex/pandora/core/import" + "github.com/yandex/pandora/core/register" +) + +type Ammo struct { + Tag string + Param1 string + Param2 string + Param3 string +} + +type Sample struct { + URL string + ShootTimeSeconds float64 +} + +type GunConfig struct { + Target string `validate:"required"` // Configuration will fail, without target defined +} + +type Gun struct { + // Configured on construction. + client grpc.ClientConn + conf GunConfig + // Configured on Bind, before shooting + aggr core.Aggregator // May be your custom Aggregator. + core.GunDeps +} + +func NewGun(conf GunConfig) *Gun { + return &Gun{conf: conf} +} + +func (g *Gun) Bind(aggr core.Aggregator, deps core.GunDeps) error { + // create gRPC stub at gun initialization + conn, err := grpc.Dial( + g.conf.Target, + grpc.WithInsecure(), + grpc.WithTimeout(time.Second), + grpc.WithUserAgent("load test, pandora custom shooter")) + if err != nil { + log.Fatalf("FATAL: %s", err) + } + g.client = *conn + g.aggr = aggr + g.GunDeps = deps + return nil +} + +func (g *Gun) Shoot(ammo core.Ammo) { + customAmmo := ammo.(*Ammo) + g.shoot(customAmmo) +} + + +func (g *Gun) case1_method(client pb.MyClient, ammo *Ammo) int { + code := 0 + // prepare list of ids from ammo + var itemIDs []int64 + for _, id := range strings.Split(ammo.Param1, ",") { + if id == "" { + continue + } + itemID, err := strconv.ParseInt(id, 10, 64) + if err != nil { + log.Printf("Ammo parse FATAL: %s", err) + code = 314 + } + itemIDs = append(itemIDs, itemID) + } + + out, err := client.GetSomeData( + context.TODO(), &pb.ItemsRequest{ + itemIDs}) + + if err != nil { + log.Printf("FATAL: %s", err) + code = 500 + } + + if out != nil { + code = 200 + } + return code +} + +func (g *Gun) case2_method(client pb.MyClient, ammo *Ammo) int { + code := 0 + // prepare item_id and warehouse_id + item_id, err := strconv.ParseInt(ammo.Param1, 10, 0) + if err != nil { + log.Printf("Failed to parse ammo FATAL", err) + code = 314 + } + warehouse_id, err2 := strconv.ParseInt(ammo.Param2, 10, 0) + if err2 != nil { + log.Printf("Failed to parse ammo FATAL", err2) + code = 314 + } + + items := []*pb.SomeItem{} + items = append(items, &pb.SomeItem{ + item_id, + warehouse_id, + 1, + ×tamp.Timestamp{time.Now().Unix(), 111} + }) + + out2, err3 := client.GetSomeDataSecond( + context.TODO(), &pb.SomeRequest{ + uuid.Must(uuid.NewV4()).String(), + 1, + items}) + if err3 != nil { + log.Printf("FATAL", err3) + code = 316 + } + + if out2 != nil { + code = 200 + } + + + return code +} + +func (g *Gun) shoot(ammo *Ammo) { + code := 0 + sample := netsample.Acquire(ammo.Tag) + + conn := g.client + client := pb.NewClient(&conn) + + switch ammo.Tag { + case "/MyCase1": + code = g.case1_method(client, ammo) + case "/MyCase2": + code = g.case2_method(client, ammo) + default: + code = 404 + } + + defer func() { + sample.SetProtoCode(code) + g.aggr.Report(sample) + }() +} + +func main() { + //debug.SetGCPercent(-1) + // Standard imports. + fs := afero.NewOsFs() + coreimport.Import(fs) + // May not be imported, if you don't need http guns and etc. + phttp.Import(fs) + + // Custom imports. Integrate your custom types into configuration system. + coreimport.RegisterCustomJSONProvider("custom_provider", func() core.Ammo { return &Ammo{} }) + + register.Gun("my_custom_gun_name", NewGun, func() GunConfig { + return GunConfig{ + Target: "default target", + } + }) + + cli.Run() +} +``` + +## Websockets + +```go +// create a package +package main + +// import some pandora stuff +// and stuff you need for your scenario +// and protobuf contracts for your grpc service + +import ( + "log" + "context" + "strconv" + "strings" + "time" + + "github.com/golang/protobuf/ptypes/timestamp" + "github.com/satori/go.uuid" + "github.com/spf13/afero" + "google.golang.org/grpc" + pb "my_package/my_protobuf_contracts" + + "github.com/yandex/pandora/cli" + "github.com/yandex/pandora/components/phttp/import" + "github.com/yandex/pandora/core" + "github.com/yandex/pandora/core/aggregator/netsample" + "github.com/yandex/pandora/core/import" + "github.com/yandex/pandora/core/register" +) + +type Ammo struct { + Tag string + Param1 string + Param2 string + Param3 string +} + +type Sample struct { + URL string + ShootTimeSeconds float64 +} + +type GunConfig struct { + Target string `validate:"required"` // Configuration will fail, without target defined +} + +type Gun struct { + // Configured on construction. + client grpc.ClientConn + conf GunConfig + // Configured on Bind, before shooting + aggr core.Aggregator // May be your custom Aggregator. + core.GunDeps +} + +func NewGun(conf GunConfig) *Gun { + return &Gun{conf: conf} +} + +func (g *Gun) Bind(aggr core.Aggregator, deps core.GunDeps) error { + // create gRPC stub at gun initialization + conn, err := grpc.Dial( + g.conf.Target, + grpc.WithInsecure(), + grpc.WithTimeout(time.Second), + grpc.WithUserAgent("load test, pandora custom shooter")) + if err != nil { + log.Fatalf("FATAL: %s", err) + } + g.client = *conn + g.aggr = aggr + g.GunDeps = deps + return nil +} + +func (g *Gun) Shoot(ammo core.Ammo) { + customAmmo := ammo.(*Ammo) + g.shoot(customAmmo) +} + + +func (g *Gun) case1_method(client pb.MyClient, ammo *Ammo) int { + code := 0 + // prepare list of ids from ammo + var itemIDs []int64 + for _, id := range strings.Split(ammo.Param1, ",") { + if id == "" { + continue + } + itemID, err := strconv.ParseInt(id, 10, 64) + if err != nil { + log.Printf("Ammo parse FATAL: %s", err) + code = 314 + } + itemIDs = append(itemIDs, itemID) + } + + out, err := client.GetSomeData( + context.TODO(), &pb.ItemsRequest{ + itemIDs}) + + if err != nil { + log.Printf("FATAL: %s", err) + code = 500 + } + + if out != nil { + code = 200 + } + return code +} + +func (g *Gun) case2_method(client pb.MyClient, ammo *Ammo) int { + code := 0 + // prepare item_id and warehouse_id + item_id, err := strconv.ParseInt(ammo.Param1, 10, 0) + if err != nil { + log.Printf("Failed to parse ammo FATAL", err) + code = 314 + } + warehouse_id, err2 := strconv.ParseInt(ammo.Param2, 10, 0) + if err2 != nil { + log.Printf("Failed to parse ammo FATAL", err2) + code = 314 + } + + items := []*pb.SomeItem{} + items = append(items, &pb.SomeItem{ + item_id, + warehouse_id, + 1, + ×tamp.Timestamp{time.Now().Unix(), 111} + }) + + out2, err3 := client.GetSomeDataSecond( + context.TODO(), &pb.SomeRequest{ + uuid.Must(uuid.NewV4()).String(), + 1, + items}) + if err3 != nil { + log.Printf("FATAL", err3) + code = 316 + } + + if out2 != nil { + code = 200 + } + + + return code +} + +func (g *Gun) shoot(ammo *Ammo) { + code := 0 + sample := netsample.Acquire(ammo.Tag) + + conn := g.client + client := pb.NewClient(&conn) + + switch ammo.Tag { + case "/MyCase1": + code = g.case1_method(client, ammo) + case "/MyCase2": + code = g.case2_method(client, ammo) + default: + code = 404 + } + + defer func() { + sample.SetProtoCode(code) + g.aggr.Report(sample) + }() +} + +func main() { + //debug.SetGCPercent(-1) + // Standard imports. + fs := afero.NewOsFs() + coreimport.Import(fs) + // May not be imported, if you don't need http guns and etc. + phttp.Import(fs) + + // Custom imports. Integrate your custom types into configuration system. + coreimport.RegisterCustomJSONProvider("custom_provider", func() core.Ammo { return &Ammo{} }) + + register.Gun("my_custom_gun_name", NewGun, func() GunConfig { + return GunConfig{ + Target: "default target", + } + }) + + cli.Run() +} +``` diff --git a/docs/rus/grpc-generator.md b/docs/content/ru/grpc-generator.md similarity index 95% rename from docs/rus/grpc-generator.md rename to docs/content/ru/grpc-generator.md index b93abae71..b3077c008 100644 --- a/docs/rus/grpc-generator.md +++ b/docs/content/ru/grpc-generator.md @@ -1,8 +1,10 @@ -[Домой](index.md) - --- - -# gRPC генератор +title: gRPC генератор +description: Настройка grpc генератора +categories: [Generator] +tags: [generator, grpc] +weight: 8 +--- Полный конфиг grpc генератора @@ -60,7 +62,3 @@ gun: - Практики использования - [RPS на инстанс](best_practices/rps-per-instance.md) - [Общий транспорт](best_practices/shared-client.md) - ---- - -[Домой](index.md) diff --git a/docs/rus/http-generator.md b/docs/content/ru/http-generator.md similarity index 95% rename from docs/rus/http-generator.md rename to docs/content/ru/http-generator.md index 7523e786e..a2eaf6688 100644 --- a/docs/rus/http-generator.md +++ b/docs/content/ru/http-generator.md @@ -1,8 +1,10 @@ -[Домой](index.md) - --- - -# HTTP генератор +title: HTTP генератор +description: Настройка http/http2 генератора +categories: [Config] +tags: [config, docs, http] +weight: 9 +--- Полный конфиг http (http2) генератора @@ -47,7 +49,3 @@ gun: - Практики использования - [RPS на инстанс](best_practices/rps-per-instance.md) - [Общий транспорт](best_practices/shared-client.md) - ---- - -[Домой](index.md) diff --git a/docs/rus/install.md b/docs/content/ru/install.md similarity index 74% rename from docs/rus/install.md rename to docs/content/ru/install.md index f2a3a14b9..ffbd08113 100644 --- a/docs/rus/install.md +++ b/docs/content/ru/install.md @@ -1,8 +1,10 @@ -[Домой](index.md) - --- - -# Установка +title: Установка +description: Как установить Yandex Pandora +categories: [Get started] +tags: [install] +weight: 1 +--- [Скачать](https://github.com/yandex/pandora/releases) релиз или собрать из сходников. @@ -20,6 +22,3 @@ go mod download GOOS=linux GOARCH=amd64 go build ``` ---- - -[Домой](index.md) diff --git a/docs/rus/load-profile.md b/docs/content/ru/load-profile.md similarity index 79% rename from docs/rus/load-profile.md rename to docs/content/ru/load-profile.md index 76c54a8e3..2bf7f97ca 100644 --- a/docs/rus/load-profile.md +++ b/docs/content/ru/load-profile.md @@ -1,10 +1,13 @@ -[К содержанию](index.md) - +--- +title: Профиль нагрузки +description: Профиль определяет, как будет изменяться и поддерживаться нагрузка +categories: [Load profile] +tags: [load_profile] +weight: 4 --- -# Профиль нагрузки - -Чтобы определить, какую нагрузку подавать на сервер, используется профиль нагрузки. Профиль определяет, как будет изменяться и поддерживаться нагрузка. +Чтобы определить, какую нагрузку подавать на сервер, используется профиль нагрузки. Профиль определяет, как будет +изменяться и поддерживаться нагрузка. ## const @@ -71,18 +74,15 @@ rps: ## unlimited -Передает столько запросов, сколько может принять цель в рамках установленных соединений без ограничений в течение указанного времени. +Передает столько запросов, сколько может принять цель в рамках установленных соединений без ограничений в течение +указанного времени. Пример: -максимальное кол-во rps втечение 30 секунд +максимальное кол-во rps в течение 30 секунд ```yaml rps: - type: unlimited - duration: 30s + type: unlimited + duration: 30s ``` - ---- - -[К содержанию](index.md) diff --git a/docs/rus/performance.md b/docs/content/ru/performance.md similarity index 72% rename from docs/rus/performance.md rename to docs/content/ru/performance.md index e92954248..fd27182ff 100644 --- a/docs/rus/performance.md +++ b/docs/content/ru/performance.md @@ -1,11 +1,10 @@ -[К содержанию](index.md) - --- - -# Pandora's performance - -- [HTTP requests to nginx](#http-requests-to-nginx) -- [Custom scenarios](#custom-scenarios) +title: Производительность Pandora +description: Результаты тестов производительности +categories: [Best practise] +tags: [config, test, performance] +weight: 13 +--- [Alexander Ivanov](mailto:ival.net@yandex.ru) made some performance tests for the gun itself. Here are the results. @@ -46,12 +45,12 @@ server { * **Connection: Close** 23k RPS -![Connection:Close, response times distribution](../images/http_connection_close_td.png) +![Connection:Close, response times distribution](../../images/http_connection_close_td.png) * **Connection: Keep-Alive** 95k RPS -![Keep-Alive, response times distribution](../images/http_keep_alive_td.png) +![Keep-Alive, response times distribution](../../images/http_keep_alive_td.png) * **Response size 10kB** maxed out network interface. OK. @@ -60,7 +59,7 @@ server { * **POST requests 100kB** maxed out network interface. OK. * **POST requests 1MB** maxed out network interface. OK. -![100 kb responses, network load](../images/http_100kb_net.png) +![100 kb responses, network load](../../images/http_100kb_net.png) @@ -71,16 +70,16 @@ server { **All good.** -![10s server delay, response times distribution](../images/http_delay_10s_td.png) +![10s server delay, response times distribution](../../images/http_delay_10s_td.png) -![10s server delay, instances count](../images/http_delay_10s_instances.png) +![10s server delay, instances count](../../images/http_delay_10s_instances.png) * **Server fail during test** OK. -![server fail emulation, response times quantiles](../images/http_srv_fail_q.png) +![server fail emulation, response times quantiles](../../images/http_srv_fail_q.png) @@ -98,8 +97,5 @@ to do this. * **Small requests** 35k RPS. OK. * **Some scenario steps with big JSON bodies** 35k RPS. OK. -![scenario steps](../images/scn_cases.png) - - --- +![scenario steps](../../images/scn_cases.png) -[К содержанию](index.md) diff --git a/docs/rus/providers.md b/docs/content/ru/providers.md similarity index 93% rename from docs/rus/providers.md rename to docs/content/ru/providers.md index c9ad1a6bb..980b85275 100644 --- a/docs/rus/providers.md +++ b/docs/content/ru/providers.md @@ -1,17 +1,10 @@ -[К содержанию](index.md) - --- - -# HTTP Ammo providers - -- [Test data](#test-data) - - [http/json](#httpjson) - - [raw (request-style)](#raw-request-style) - - [uri-style](#uri-style) -- [Features](#features) - - [Ammo filters](#ammo-filters) - - [HTTP Ammo middlewares](#http-ammo-middlewares) - - [HTTP Ammo preloaded](#http-ammo-preloaded) +title: HTTP Ammo providers +description: HTTP Ammo provider is a source of test data - it makes ammo object +categories: [Provider] +tags: [provider, http] +weight: 6 +--- HTTP Ammo provider is a source of test data: it makes ammo object. @@ -231,7 +224,3 @@ pools: ... preload: true ``` - ---- - -[К содержанию](index.md) diff --git a/docs/rus/scenario-grpc-generator.md b/docs/content/ru/scenario-grpc-generator.md similarity index 84% rename from docs/rus/scenario-grpc-generator.md rename to docs/content/ru/scenario-grpc-generator.md index c387af08a..5a5a3fc36 100644 --- a/docs/rus/scenario-grpc-generator.md +++ b/docs/content/ru/scenario-grpc-generator.md @@ -1,29 +1,10 @@ -[Домой](index.md) - --- - -# Сценарный генератор / gRPC - -- [Конфигурация](#конфигурация) - - [Генератор](#генератор) - - [Провайдер](#провайдер) -- [Описание формата сценариев](#описание-формата-сценариев) - - [Общий принцип](#общий-принцип) - - [HCL пример](#hcl-пример) - - [YAML пример](#yaml-пример) - - [Locals](#locals) -- [Возможности](#возможности) - - [Вызовы](#вызовы) - - [Шаблонизатор](#шаблонизатор) - - [Имена переменных в шаблонрах](#имена-переменных-в-шаблонах) - - [Функции в шаблонах](#функции-в-шаблонах) - - [Preprocessors](#preprocessors) - - [prepare](#prepare) - - [Postprocessors](#postprocessors) - - [assert/response](#assertresponse) - - [Scenarios](#scenarios) - - [Sources](#sources) -- [Смотри так же](#cмотри-так-же) +title: Scenario generator / gRPC +description: Scenario generator / gRPC +categories: [generator] +tags: [scenario, generator, grpc] +weight: 10 +--- ## Конфигурация @@ -320,11 +301,4 @@ scenario "scenario_name" { # Смотри так же - [gRPC генератор](grpc-generator.md) -- Практики использования - - [RPS на инстанс](best_practices/rps-per-instance.md) - - [Общий транспорт](best_practices/shared-client.md) - - ---- - -[Домой](index.md) +- [Практики использования](best-practices) diff --git a/docs/rus/scenario-http-generator.md b/docs/content/ru/scenario-http-generator.md similarity index 87% rename from docs/rus/scenario-http-generator.md rename to docs/content/ru/scenario-http-generator.md index 7339b2e2b..d3f19d917 100644 --- a/docs/rus/scenario-http-generator.md +++ b/docs/content/ru/scenario-http-generator.md @@ -1,31 +1,10 @@ -[Домой](index.md) - --- - -# Сценарный генератор / HTTP - -- [Конфигурация](#конфигурация) - - [Генератор](#генератор) - - [Провайдер](#провайдер) -- [Описание формата сценариев](#описание-формата-сценариев) - - [Общий принцип](#общий-принцип) - - [HCL пример](#hcl-пример) - - [YAML пример](#yaml-пример) - - [Locals](#locals) -- [Возможности](#возможности) - - [Запросы](#запросы) - - [Шаблонизатор](#шаблонизатор) - - [Имена переменных в шаблонрах](#имена-переменных-в-шаблонах) - - [Функции в шаблонах](#функции-в-шаблонах) - - [Preprocessors](#preprocessors) - - [Postprocessors](#postprocessors) - - [var/jsonpath](#varjsonpath) - - [var/xpath](#varxpath) - - [var/header](#varheader) - - [assert/response](#assertresponse) - - [Scenarios](#scenarios) - - [Sources](#sources) -- [Смотри так же](#cмотри-так-же) +title: Scenario generator / HTTP +description: Scenario generator / HTTP +categories: [generator] +tags: [scenario, generator, http] +weight: 9 +--- ## Конфигурация @@ -243,7 +222,7 @@ scenarios: Так как используется стандартные шаблонизатор Го в нем можно использовать встроенные функции https://pkg.go.dev/text/template#hdr-Functions -А так же некоторые функции +А так же некоторые функции - randInt - randString @@ -481,12 +460,5 @@ scenario "scenario_second" { # Смотри так же - [HTTP генератор](http-generator.md) -- Практики использования - - [RPS на инстанс](best_practices/rps-per-instance.md) - - [Общий транспорт](best_practices/shared-client.md) - - - ---- +- [Практики использования](best-practices) -[Домой](index.md) diff --git a/docs/content/ru/scenario/_index.md b/docs/content/ru/scenario/_index.md new file mode 100644 index 000000000..df8c7cb44 --- /dev/null +++ b/docs/content/ru/scenario/_index.md @@ -0,0 +1,6 @@ +--- +title: Сценарии +linkTitle: Сценарии +description: Общие настройки в сценарных генераторах +weight: 11 +--- diff --git a/docs/rus/scenario/functions.md b/docs/content/ru/scenario/functions.md similarity index 96% rename from docs/rus/scenario/functions.md rename to docs/content/ru/scenario/functions.md index b3774821c..99913064b 100644 --- a/docs/rus/scenario/functions.md +++ b/docs/content/ru/scenario/functions.md @@ -1,8 +1,10 @@ -[Домой](../index.md) - --- - -# Функции рандомизации +title: Функции рандомизации +description: Вы можете использовать функции для генерации случайных значений +categories: [Scenario] +tags: [scenario, function] +weight: 3 +--- Вы можете использовать функции для генерации рандомных значений @@ -10,7 +12,7 @@ - randString - uuid -Использовать их можно в разных частях сценариев с некоторыми особенностями использования +Использовать их можно в разных частях сценариев с некоторыми особенностями использования - [В шаблона](#в-шаблонах) - [В источник данных - variables](#в-источнике-данных---variables) @@ -163,7 +165,3 @@ preprocessor { - [Сценарный генератор / HTTP](../scenario-http-generator.md) - [Сценарный генератор / gRPC](../scenario-grpc-generator.md) - ---- - -[Домой](../index.md) diff --git a/docs/rus/scenario/locals.md b/docs/content/ru/scenario/locals.md similarity index 93% rename from docs/rus/scenario/locals.md rename to docs/content/ru/scenario/locals.md index fe4160d5b..28558f4a5 100644 --- a/docs/rus/scenario/locals.md +++ b/docs/content/ru/scenario/locals.md @@ -1,10 +1,12 @@ -[Домой](../index.md) - +--- +title: Locals +description: Блок locals в hcl +categories: [Scenario] +tags: [scenario, local] +weight: 2 --- -# Locals - -Предисловие: +Предисловие: Формирование сценария из hcl состоит из 2-х этапов: - этап парсинга - преобразовывает hcl файл в внутреннюю структуру генератора @@ -17,8 +19,8 @@ ## HCL -Так же как и в terraform вы можете использовать блок `locals`, который вы можете использовать для создания -дополнительных переменных. Важно, что данные переменные будут использоваться только при парсинге HCL и их нельзя +Так же как и в terraform вы можете использовать блок `locals`, который вы можете использовать для создания +дополнительных переменных. Важно, что данные переменные будут использоваться только при парсинге HCL и их нельзя использовать на этапе выполнения. ### Функции @@ -94,7 +96,3 @@ requests: - [Сценарный генератор / HTTP](../scenario-http-generator.md) - [Сценарный генератор / gRPC](../scenario-grpc-generator.md) - ---- - -[Домой](../index.md) diff --git a/docs/rus/scenario/variable_source.md b/docs/content/ru/scenario/variable_source.md similarity index 94% rename from docs/rus/scenario/variable_source.md rename to docs/content/ru/scenario/variable_source.md index a12f9d146..deb5538b1 100644 --- a/docs/rus/scenario/variable_source.md +++ b/docs/content/ru/scenario/variable_source.md @@ -1,8 +1,10 @@ -[Домой](../index.md) - --- - -# Источники переменных +title: Источники переменных +description: Блок variable_source в сценариях +categories: [Scenario] +tags: [scenario, source, variable] +weight: 1 +--- Используются в @@ -128,7 +130,3 @@ variable_source "global" "variables" { - [Сценарный генератор / HTTP](../scenario-http-generator.md) - [Сценарный генератор / gRPC](../scenario-grpc-generator.md) - ---- - -[Домой](../index.md) diff --git a/docs/content/ru/search.md b/docs/content/ru/search.md new file mode 100644 index 000000000..4488ca9c3 --- /dev/null +++ b/docs/content/ru/search.md @@ -0,0 +1,4 @@ +--- +title: Результаты поиска +layout: search +--- diff --git a/docs/rus/startup.md b/docs/content/ru/startup.md similarity index 91% rename from docs/rus/startup.md rename to docs/content/ru/startup.md index 4177dec8d..895a36404 100644 --- a/docs/rus/startup.md +++ b/docs/content/ru/startup.md @@ -1,8 +1,10 @@ -[К содержанию](index.md) - --- - -# Профиль создание инстансов +title: Профиль создания инстансов +description: Сколько инстансов вам необходимо, и как быстро они будут вам доступны +categories: [Startup] +tags: [startup] +weight: 5 +--- Вы можете контролировать профиль создания инстансов. @@ -87,9 +89,3 @@ startup: - type: once times: 10 ``` - - - ---- - -[К содержанию](index.md) diff --git a/docs/rus/tutorial.md b/docs/content/ru/tutorial.md similarity index 94% rename from docs/rus/tutorial.md rename to docs/content/ru/tutorial.md index 47e09ccd7..7c5940ed4 100644 --- a/docs/rus/tutorial.md +++ b/docs/content/ru/tutorial.md @@ -1,8 +1,8 @@ -[К содержанию](index.md) - --- - -# Первый тест +title: Ваш первый тест +description: +weight: 3 +--- You can use Pandora alone or use it with [Yandex.Tank](https://yandextank.readthedocs.io/en/latest/core_and_modules.html#pandora) as a test runner and [Overload](https://overload.yandex.net) as a result viewer. In the second case Pandora's configuration is the same, but you will embed it into Yandex.Tank's config. @@ -44,7 +44,3 @@ pandora load.yaml ``` The results are in `phout.log`. Use [Yandex.Tank](https://yandextank.readthedocs.io/en/latest/core_and_modules.html#pandora) and [Overload](https://overload.yandex.net) to plot them. - ---- - -[К содержанию](index.md) diff --git a/docs/docsy.work b/docs/docsy.work new file mode 100644 index 000000000..074dc2a12 --- /dev/null +++ b/docs/docsy.work @@ -0,0 +1,5 @@ +go 1.19 + +use . +use ../docsy/ // Local docsy clone resides in sibling folder to this project +// use ./themes/docsy/ // Local docsy clone resides in themes folder diff --git a/docs/docsy.work.sum b/docs/docsy.work.sum new file mode 100644 index 000000000..e69de29bb diff --git a/docs/eng/best-practices.md b/docs/eng/best-practices.md deleted file mode 100644 index 9063978ec..000000000 --- a/docs/eng/best-practices.md +++ /dev/null @@ -1,5 +0,0 @@ -# Практики использования - -- [Discard Overflow](best_practices/discard-overflow.md) -- [RPS per instance](./best_practices/rps-per-instance.md) -- [Shared client](best_practices/shared-client.md) \ No newline at end of file diff --git a/docs/go.mod b/docs/go.mod new file mode 100644 index 000000000..2f681af5f --- /dev/null +++ b/docs/go.mod @@ -0,0 +1,5 @@ +module github.com/yadnex/pandora/docs + +go 1.12 + +require github.com/google/docsy v0.10.1-0.20240529105443-333c2f8d4172 // indirect - v0.10.0-12-g333c2f8 diff --git a/docs/go.sum b/docs/go.sum new file mode 100644 index 000000000..f74505141 --- /dev/null +++ b/docs/go.sum @@ -0,0 +1,6 @@ +github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= +github.com/google/docsy v0.10.1-0.20240529105443-333c2f8d4172 h1:1gAAuOfHRok/hJqfF+wpjOYqlH0d76dwUsskLEnOzxo= +github.com/google/docsy v0.10.1-0.20240529105443-333c2f8d4172/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc= +github.com/theNewDynamic/gohugo-theme-ananke v0.0.0-20240503174335-33fbda0e9d3e h1:7gGo4gWBXKqjctzjetYSPhOGJKbVBsNgkiv5oJ3LgJc= +github.com/theNewDynamic/gohugo-theme-ananke v0.0.0-20240503174335-33fbda0e9d3e/go.mod h1:yY14BLqqh5G61rO81YcJKMHY1rClY5iIiUK+K2JKSUM= +github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= diff --git a/docs/hugo-disabled.toml b/docs/hugo-disabled.toml new file mode 100644 index 000000000..f9006d69e --- /dev/null +++ b/docs/hugo-disabled.toml @@ -0,0 +1,211 @@ +baseURL = "https://yandex.github.io/" +title = "Goldydocs" + +# Language settings +contentDir = "content/en" +defaultContentLanguage = "en" +defaultContentLanguageInSubdir = false +# Useful when translating. +enableMissingTranslationPlaceholders = true + +enableRobotsTXT = true + +# Will give values to .Lastmod etc. +enableGitInfo = true + +# Comment out to enable taxonomies in Docsy +# disableKinds = ["taxonomy", "taxonomyTerm"] + +# You can add your own taxonomies +[taxonomies] +tag = "tags" +category = "categories" + +[params.taxonomy] +# set taxonomyCloud = [] to hide taxonomy clouds +taxonomyCloud = ["tags", "categories"] + +# If used, must have same length as taxonomyCloud +taxonomyCloudTitle = ["Tag Cloud", "Categories"] + +# set taxonomyPageHeader = [] to hide taxonomies on the page headers +taxonomyPageHeader = ["tags", "categories"] + +# Highlighting config +pygmentsCodeFences = true +pygmentsUseClasses = false +# Use the new Chroma Go highlighter in Hugo. +pygmentsUseClassic = false +#pygmentsOptions = "linenos=table" +# See https://help.farbox.com/pygments.html +pygmentsStyle = "tango" + +# Configure how URLs look like per section. +[permalinks] +blog = "/:section/:year/:month/:day/:slug/" + +# Image processing configuration. +[imaging] +resampleFilter = "CatmullRom" +quality = 75 +anchor = "smart" + +# Language configuration + +[languages] +[languages.en] +languageName ="English" +title = "Pandora" +[languages.en.params] +description = "Yandex Pandora Documentation" + +[languages.no] +languageName ="Русский" +contentDir = "content/no" +title = "Pandora" +[languages.no.params] +description = "Документация Yandex Pandora" +time_format_default = "02.01.2006" +time_format_blog = "02.01.2006" + +[markup] + [markup.goldmark] + [markup.goldmark.parser.attribute] + block = true + [markup.goldmark.renderer] + unsafe = true + [markup.highlight] + # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html + style = "tango" + # Uncomment if you want your chosen highlight style used for code blocks without a specified language + # guessSyntax = "true" + +# Comment out if you don't want the "print entire section" link enabled. +[outputs] +section = ["HTML", "print", "RSS"] + +# Everything below this are Site Params + +[params] +privacy_policy = "https://policies.google.com/privacy" + +# First one is picked as the Twitter card image if not set on page. +# images = ["images/project-illustration.png"] + +# Menu title if your navbar has a versions selector to access old versions of your site. +# This menu appears only if you have at least one [params.versions] set. +version_menu = "Releases" + +# Flag used in the "version-banner" partial to decide whether to display a +# banner on every page indicating that this is an archived version of the docs. +# Set this flag to "true" if you want to display the banner. +archived_version = false + +# The version number for the version of the docs represented in this doc set. +# Used in the "version-banner" partial to display a version number for the +# current doc set. +version = "0.0" + +# A link to latest version of the docs. Used in the "version-banner" partial to +# point people to the main doc site. +url_latest_version = "https://example.com" + +# Repository configuration (URLs for in-page links to opening issues and suggesting changes) +github_repo = "https://github.com/yandex/pandora" +# An optional link to a related project repo. For example, the sibling repository where your product code lives. +github_project_repo = "https://github.com/google/docsy" + +# Specify a value here if your content directory is not in your repo's root directory +# github_subdir = "" + +# Uncomment this if your GitHub repo does not have "main" as the default branch, +# or specify a new value if you want to reference another branch in your GitHub links +github_branch= "main" + +# Google Custom Search Engine ID. Remove or comment out to disable search. +gcs_engine_id = "d72aa9b2712488cc3" + +# Enable Lunr.js offline search +offlineSearch = false + +# Enable syntax highlighting and copy buttons on code blocks with Prism +prism_syntax_highlighting = false + +[params.copyright] + authors = "Docsy Authors | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) | " + from_year = 2018 + +# User interface configuration +[params.ui] +# Set to true to disable breadcrumb navigation. +breadcrumb_disable = false +# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar +navbar_logo = true +# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage. +navbar_translucent_over_cover_disable = false +# Enable to show the side bar menu in its compact state. +sidebar_menu_compact = false +# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) +sidebar_search_disable = false + +# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. +# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. +# If you want this feature, but occasionally need to remove the "Feedback" section from a single page, +# add "hide_feedback: true" to the page's front matter. +#[params.ui.feedback] +#enable = true +## The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). +#yes = 'Glad to hear it! Please tell us how we can improve.' +#no = 'Sorry to hear that. Please tell us how we can improve.' + +# Adds a reading time to the top of each doc. +# If you want this feature, but occasionally need to remove the Reading time from a single page, +# add "hide_readingtime: true" to the page's front matter +[params.ui.readingtime] +enable = false + +[params.links] +# End user relevant links. These will show up on left side of footer and in the community page if you have one. +[[params.links.user]] + name = "User mailing list" + url = "https://example.org/mail" + icon = "fa fa-envelope" + desc = "Discussion and help from your fellow users" +[[params.links.user]] + name ="Twitter" + url = "https://example.org/twitter" + icon = "fab fa-twitter" + desc = "Follow us on Twitter to get the latest news!" +[[params.links.user]] + name = "Stack Overflow" + url = "https://example.org/stack" + icon = "fab fa-stack-overflow" + desc = "Practical questions and curated answers" +# Developer relevant links. These will show up on right side of footer and in the community page if you have one. +[[params.links.developer]] + name = "GitHub" + url = "https://github.com/google/docsy" + icon = "fab fa-github" + desc = "Development takes place here!" +[[params.links.developer]] + name = "Slack" + url = "https://example.org/slack" + icon = "fab fa-slack" + desc = "Chat with other project developers" +[[params.links.developer]] + name = "Developer mailing list" + url = "https://example.org/mail" + icon = "fa fa-envelope" + desc = "Discuss development issues around the project" + +# hugo module configuration + +[module] + # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace: + # workspace = "docsy.work" + [module.hugoVersion] + extended = true + min = "0.110.0" + [[module.imports]] + path = "github.com/google/docsy" + disable = false diff --git a/docs/hugo.yaml b/docs/hugo.yaml new file mode 100644 index 000000000..1a39bdaa3 --- /dev/null +++ b/docs/hugo.yaml @@ -0,0 +1,211 @@ +baseURL: https://yandex.github.io/pandora +title: Yandex Pandora + +# cSpell:ignore goldmark github hugo readingtime docsy subdir lastmod pygments linenos catmullrom norsk gu + +# Language settings +contentDir: content/en +defaultContentLanguage: en +defaultContentLanguageInSubdir: false +# Useful when translating. +enableMissingTranslationPlaceholders: true + +enableRobotsTXT: true + +# Will give values to .Lastmod etc. +enableGitInfo: true + +# Comment out to enable taxonomies in Docsy +# disableKinds: [taxonomy, taxonomyTerm] + +# You can add your own taxonomies +taxonomies: + tag: tags + category: categories + +# Highlighting config +pygmentsCodeFences: true +pygmentsUseClasses: false +# Use the new Chroma Go highlighter in Hugo. +pygmentsUseClassic: false +# pygmentsOptions: "linenos=table" +# See https://help.farbox.com/pygments.html +pygmentsStyle: tango + +# Configure how URLs look like per section. +permalinks: + blog: /:section/:year/:month/:day/:slug/ + +# Image processing configuration. +imaging: + resampleFilter: CatmullRom + quality: 75 + anchor: smart + +# Language configuration +languages: + en: + languageName: English + title: Yandex Pandora + params: + description: Yandex Pandora Documentation + # cSpell:disable + ru: + languageName: Русский + contentDir: content/ru + title: Yandex Pandora + params: + description: Документация Yandex Pandora + time_format_default: 02.01.2006 + time_format_blog: 02.01.2006 + # cSpell:enable + +markup: + goldmark: + parser: + attribute: + block: true + renderer: + unsafe: true + highlight: + # See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html + style: tango + # Uncomment if you want your chosen highlight style used for code blocks without a specified language + # guessSyntax: true + +# Everything below this are Site Params + +# Comment out if you don't want the "print entire section" link enabled. +outputs: + section: [HTML, print, RSS] + +params: + taxonomy: + # set taxonomyCloud = [] to hide taxonomy clouds + taxonomyCloud: [tags, categories] + + # If used, must have same length as taxonomyCloud + taxonomyCloudTitle: [Tag Cloud, Categories] + + # set taxonomyPageHeader = [] to hide taxonomies on the page headers + taxonomyPageHeader: [tags, categories] + + privacy_policy: https://policies.google.com/privacy + + # First one is picked as the Twitter card image if not set on page. + # images: [images/project-illustration.png] + + # Menu title if your navbar has a versions selector to access old versions of your site. + # This menu appears only if you have at least one [params.versions] set. + version_menu: Releases + + # Flag used in the "version-banner" partial to decide whether to display a + # banner on every page indicating that this is an archived version of the docs. + # Set this flag to "true" if you want to display the banner. + archived_version: false + + # The version number for the version of the docs represented in this doc set. + # Used in the "version-banner" partial to display a version number for the + # current doc set. + version: 0.0 + + # A link to latest version of the docs. Used in the "version-banner" partial to + # point people to the main doc site. + url_latest_version: https://yandexpandora.readthedocs.io/en/latest/ + + # Repository configuration (URLs for in-page links to opening issues and suggesting changes) + github_repo: https://github.com/yandex/pandora + + # An optional link to a related project repo. For example, the sibling repository where your product code lives. + github_project_repo: https://github.com/yandex/pandora + + # Specify a value here if your content directory is not in your repo's root directory + github_subdir: "docs/" + + # Uncomment this if your GitHub repo does not have "main" as the default branch, + # or specify a new value if you want to reference another branch in your GitHub links + github_branch: dev + + # Google Custom Search Engine ID. Remove or comment out to disable search. + gcs_engine_id: d72aa9b2712488cc3 + + # Enable Lunr.js offline search + offlineSearch: false + + # Enable syntax highlighting and copy buttons on code blocks with Prism + prism_syntax_highlighting: false + + copyright: + authors: Docsy Authors | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) | + from_year: 2018 + + # User interface configuration + ui: + # Set to true to disable breadcrumb navigation. + breadcrumb_disable: false + # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar + navbar_logo: true + # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage. + navbar_translucent_over_cover_disable: false + # Enable to show the side bar menu in its compact state. + sidebar_menu_compact: false + # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled) + sidebar_search_disable: true + + # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events. + # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set. + # If you want this feature, but occasionally need to remove the "Feedback" section from a single page, + # add "hide_feedback: true" to the page's front matter. +# feedback: +# enable: true +# # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful). +# 'yes': >- +# Glad to hear it! Please tell us how we can improve. +# 'no': >- +# Sorry to hear that. Please tell us how we can improve. + + # Adds a reading time to the top of each doc. + # If you want this feature, but occasionally need to remove the Reading time from a single page, + # add "hide_readingtime: true" to the page's front matter + readingtime: + enable: false + + links: + # End user relevant links. These will show up on left side of footer and in the community page if you have one. + user: + - name: User mailing list + url: https://example.org/mail + icon: fa fa-envelope + desc: Discussion and help from your fellow users + - name: Twitter + url: https://example.org/twitter + icon: fab fa-twitter + desc: Follow us on Twitter to get the latest news! + - name: Stack Overflow + url: https://example.org/stack + icon: fab fa-stack-overflow + desc: Practical questions and curated answers + # Developer relevant links. These will show up on right side of footer and in the community page if you have one. + developer: + - name: GitHub + url: https://github.com/google/docsy + icon: fab fa-github + desc: Development takes place here! + - name: Slack + url: https://example.org/slack + icon: fab fa-slack + desc: Chat with other project developers + - name: Developer mailing list + url: https://example.org/mail + icon: fa fa-envelope + desc: Discuss development issues around the project + +module: + # Uncomment the next line to build and serve using local docsy clone declared in the named Hugo workspace: + # workspace: docsy.work + hugoVersion: + extended: true + min: 0.110.0 + imports: + - path: github.com/google/docsy + disable: false diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 4a3a104a8..000000000 --- a/docs/index.md +++ /dev/null @@ -1,28 +0,0 @@ -# Welcome to Pandora's documentation! - -Pandora is a high-performance load generator in Go language. It has built-in HTTP(S) and HTTP/2 support and you can -write your own load scenarios in Go, compiling them just before your test. - -## Table of content - -- [Installation](eng/install.md) -- [Configuration](eng/config.md) -- [Your first test](eng/tutorial.md) -- [Load profile](eng/load-profile.md) -- [Instance startup profile](eng/startup.md) -- [HTTP providers](eng/providers.md) -- [HTTP generators](eng/http-generator.md) -- [gRPC generators](eng/grpc-generator.md) -- [Scenario generator / HTTP](eng/scenario-http-generator.md) -- [Scenario generator / gRPC](eng/scenario-grpc-generator.md) -- [Custom guns](eng/custom.md) -- [Best practices](eng/best-practices.md) - - [Discard Overflow](eng/best_practices/discard-overflow.md) - - [RPS на инстанс](eng/best_practices/rps-per-instance.md) - - [Общий транспорт](eng/best_practices/shared-client.md) -- [Pandora’s performance](eng/performance.md) -- [Architectural overview](eng/architecture.md) - ---- - -[Русский](rus/index.md) diff --git a/docs/layouts/404.html b/docs/layouts/404.html new file mode 100644 index 000000000..d32828c8b --- /dev/null +++ b/docs/layouts/404.html @@ -0,0 +1,6 @@ +{{ define "main" -}} +
+

Not found

+

Oops! This page doesn't exist. Try going back to the home page.

+
+{{- end }} diff --git a/docs/layouts/_default/_markup/render-codeblock-chem.html b/docs/layouts/_default/_markup/render-codeblock-chem.html new file mode 100644 index 000000000..148085772 --- /dev/null +++ b/docs/layouts/_default/_markup/render-codeblock-chem.html @@ -0,0 +1,18 @@ +{{ .Page.Store.Set "hasmhchem" true -}} + +{{/* set default delimiters */ -}} +{{ $delimiter_left := "$$" -}} +{{ $delimiter_right := "$$" -}} + +{{/* override delimiters if set in config file */ -}} +{{ with $.Page.Site.Params.katex.options.delimiters -}} + {{ range first 1 ( where . "display" true ) -}} + {{ $delimiter_left = index . "left" -}} + {{ $delimiter_right = index . "right" -}} + {{ end -}} +{{ end -}} + +{{/* output of chemical formulae */}} +
{{ $delimiter_left -}} +{{ .Inner | safeHTML -}} +{{ $delimiter_right -}}
{{ "" -}} diff --git a/docs/layouts/_default/_markup/render-codeblock-math.html b/docs/layouts/_default/_markup/render-codeblock-math.html new file mode 100644 index 000000000..830869490 --- /dev/null +++ b/docs/layouts/_default/_markup/render-codeblock-math.html @@ -0,0 +1,18 @@ +{{ .Page.Store.Set "hasKaTeX" true -}} + +{{/* set default delimiters */ -}} +{{ $delimiter_left := "$$" -}} +{{ $delimiter_right := "$$" -}} + +{{/* override delimiters if set in config file */ -}} +{{ with $.Page.Site.Params.katex.options.delimiters -}} + {{ range first 1 ( where . "display" true ) -}} + {{ $delimiter_left = index . "left" -}} + {{ $delimiter_right = index . "right" -}} + {{ end -}} +{{ end -}} + +{{/* output of equation */}} +
{{ $delimiter_left -}} +{{ .Inner | safeHTML -}} +{{ $delimiter_right }}
{{ "" -}} \ No newline at end of file diff --git a/docs/layouts/_default/_markup/render-codeblock-mermaid.html b/docs/layouts/_default/_markup/render-codeblock-mermaid.html new file mode 100644 index 000000000..6c52c7b17 --- /dev/null +++ b/docs/layouts/_default/_markup/render-codeblock-mermaid.html @@ -0,0 +1,5 @@ +{{ .Page.Store.Set "hasmermaid" true -}} + +
+  {{- .Inner -}}
+
diff --git a/docs/layouts/_default/_markup/td-render-heading.html b/docs/layouts/_default/_markup/td-render-heading.html new file mode 100644 index 000000000..9b470cede --- /dev/null +++ b/docs/layouts/_default/_markup/td-render-heading.html @@ -0,0 +1,8 @@ + + {{- .Text | safeHTML -}} + {{ template "_default/_markup/_td-heading-self-link.html" . -}} + + +{{- define "_default/_markup/_td-heading-self-link.html" -}} + +{{- end -}} diff --git a/docs/layouts/_default/baseof.html b/docs/layouts/_default/baseof.html new file mode 100644 index 000000000..ab1f8fd30 --- /dev/null +++ b/docs/layouts/_default/baseof.html @@ -0,0 +1,35 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+ + +
+ {{ partial "version-banner.html" . }} + {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} + {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+{{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/docs/layouts/_default/content.html b/docs/layouts/_default/content.html new file mode 100644 index 000000000..be714efe2 --- /dev/null +++ b/docs/layouts/_default/content.html @@ -0,0 +1,17 @@ +
+

{{ .Title }}

+ {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} +
+ {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
+ {{ .Content }} + {{ partial "feedback.html" . -}} + {{ if (.Site.Config.Services.Disqus.Shortname) -}} +
+ {{- partial "disqus-comment.html" . -}} + {{ end -}} +
+{{/**/ -}} diff --git a/docs/layouts/_default/list.html b/docs/layouts/_default/list.html new file mode 100644 index 000000000..0666aebfd --- /dev/null +++ b/docs/layouts/_default/list.html @@ -0,0 +1,19 @@ +{{ define "main" }} +
+

{{ .Title }}

+ {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} +
+ {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
+ {{ .Content }} + {{ partial "section-index.html" . -}} + {{ partial "feedback.html" . -}} + {{ if (.Site.Config.Services.Disqus.Shortname) -}} +
+ {{- partial "disqus-comment.html" . -}} + {{ end -}} +
+{{ end -}} diff --git a/docs/layouts/_default/search.html b/docs/layouts/_default/search.html new file mode 100644 index 000000000..7025f80f9 --- /dev/null +++ b/docs/layouts/_default/search.html @@ -0,0 +1,21 @@ +{{ define "main" -}} +
+
+

{{ .Title }}

+{{ with .Site.Params.gcs_engine_id -}} + + +{{ end -}} +
+
+{{ end }} diff --git a/docs/layouts/_default/single.html b/docs/layouts/_default/single.html new file mode 100644 index 000000000..49bb662ad --- /dev/null +++ b/docs/layouts/_default/single.html @@ -0,0 +1,3 @@ +{{ define "main" }} +{{ .Render "content" }} +{{ end }} diff --git a/docs/layouts/_default/taxonomy.html b/docs/layouts/_default/taxonomy.html new file mode 100644 index 000000000..ff6b8deef --- /dev/null +++ b/docs/layouts/_default/taxonomy.html @@ -0,0 +1,32 @@ +{{ define "main" }} +
+
+

{{ with .Data.Singular }}{{ . | humanize }}: {{ end }}{{ .Title }}

+
+ {{ .Content }} +
+
+ {{ range .Pages }} + {{ $manualLink := cond (isset .Params "manuallink") .Params.manualLink ( cond (isset .Params "manuallinkrelref") (relref . .Params.manualLinkRelref) .RelPermalink) }} +
+

{{- .Title -}}

+ {{ if not .Site.Params.ui.taxonomy_breadcrumb_disable -}} + {{/* Use breadcrumb partial, but remove attributes that are invalid or inappropriate in this page-summary context. */ -}} + {{ partial "breadcrumb.html" . + | replaceRE ` aria-\w+=\".*?\"|(breadcrumb-item) active` "$1" | safeHTML + -}} + {{ end -}} +

{{ .Description | markdownify }}

+
+ {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
+
+ {{ end }} +
+ {{ humanize ( T "ui_all" ) }} {{ with .Data.Plural }}{{ . | humanize }}{{ end }} +
+
+{{ end }} diff --git a/docs/layouts/_default/terms.html b/docs/layouts/_default/terms.html new file mode 100644 index 000000000..74af83e26 --- /dev/null +++ b/docs/layouts/_default/terms.html @@ -0,0 +1,8 @@ +{{ define "main" -}} +
+
+

{{ .Title }}

+ {{ partial "taxonomy_terms_cloud.html" (dict "context" . "taxo" ( lower .Title ) ) -}} +
+
+{{- end }} diff --git a/docs/layouts/_internal/google_analytics.html b/docs/layouts/_internal/google_analytics.html new file mode 100644 index 000000000..495e57b5e --- /dev/null +++ b/docs/layouts/_internal/google_analytics.html @@ -0,0 +1,30 @@ +{{/* + + This is a copy of https://github.com/gohugoio/hugo/pull/12505, + which changes all `{{- ... }}` to `{{- ... }}. Drop this file if + and once it is merged. + +*/ -}} + +{{ if not site.Config.Privacy.GoogleAnalytics.Disable }} + {{- with site.Config.Services.GoogleAnalytics.ID }} + {{- if strings.HasPrefix (lower .) "ua-" }} + {{- warnf "Google Analytics 4 (GA4) replaced Google Universal Analytics (UA) effective 1 July 2023. See https://support.google.com/analytics/answer/11583528. Create a GA4 property and data stream, then replace the Google Analytics ID in your site configuration with the new value." }} + {{- else }} + + + {{- end }} + {{- end }} +{{- end -}} \ No newline at end of file diff --git a/docs/layouts/blog/baseof.html b/docs/layouts/blog/baseof.html new file mode 100644 index 000000000..97f5951ae --- /dev/null +++ b/docs/layouts/blog/baseof.html @@ -0,0 +1,38 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+ + +
+ {{ with .CurrentSection.OutputFormats.Get "rss" -}} + + + + {{ end -}} + {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/docs/layouts/blog/baseof.print.html b/docs/layouts/blog/baseof.print.html new file mode 100644 index 000000000..21e63c5f7 --- /dev/null +++ b/docs/layouts/blog/baseof.print.html @@ -0,0 +1,29 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+
+
+
+
+
+ {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + diff --git a/docs/layouts/blog/content.html b/docs/layouts/blog/content.html new file mode 100644 index 000000000..dbb655913 --- /dev/null +++ b/docs/layouts/blog/content.html @@ -0,0 +1,23 @@ +
+

{{ .Title }}

+ {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} +
+ {{ with .Params.author }}{{ T "post_byline_by" }} {{ . | markdownify }} |{{ end}} + +
+
+ {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
+ {{ .Content }} + {{ if (.Site.Config.Services.Disqus.Shortname) -}} +
+ {{- partial "disqus-comment.html" . -}} +
+ {{ end -}} + + {{ partial "pager.html" . }} + {{ partial "page-meta-lastmod.html" . -}} +
diff --git a/docs/layouts/blog/list.html b/docs/layouts/blog/list.html new file mode 100644 index 000000000..43f536ae9 --- /dev/null +++ b/docs/layouts/blog/list.html @@ -0,0 +1,40 @@ +{{ define "main" }} +{{ if (and .Parent .Parent.IsHome) -}} + {{ $.Scratch.Set "blog-pages" (where .Site.RegularPages "Section" .Section) -}} +{{ else -}} + {{$.Scratch.Set "blog-pages" .Pages -}} +{{ end -}} + +
+ {{ if .Pages -}} + {{ $pag := .Paginate (( $.Scratch.Get "blog-pages").GroupByDate "2006" ) -}} + {{ range $pag.PageGroups -}} +
{{ T "post_posts_in" }} {{ .Key }}
+ + {{ end -}} + {{ end }} +
+
+ {{ if .Pages -}} + {{ template "_internal/pagination.html" . -}} + {{ end -}} +
+{{ end -}} diff --git a/docs/layouts/blog/section.print.html b/docs/layouts/blog/section.print.html new file mode 100644 index 000000000..1b0401588 --- /dev/null +++ b/docs/layouts/blog/section.print.html @@ -0,0 +1,3 @@ +{{ define "main" }} +{{ partial "print/render" . }} +{{ end }} diff --git a/docs/layouts/blog/single.html b/docs/layouts/blog/single.html new file mode 100644 index 000000000..00cb3ab91 --- /dev/null +++ b/docs/layouts/blog/single.html @@ -0,0 +1,3 @@ +{{ define "main" }} +{{ .Render "content" }} +{{ end }} \ No newline at end of file diff --git a/docs/layouts/community/list.html b/docs/layouts/community/list.html new file mode 100644 index 000000000..4ad718f16 --- /dev/null +++ b/docs/layouts/community/list.html @@ -0,0 +1,24 @@ +{{ define "main" -}} + +
+
+
+
+ +

{{ T "community_join" . }}

+

{{ T "community_introduce" . }}

+ +
+
+
+{{ partial "community_links.html" . -}} + +{{ with .Content -}} +
+{{ . }} +
+{{- end -}} + +{{ end }} diff --git a/docs/layouts/docs/baseof.html b/docs/layouts/docs/baseof.html new file mode 100644 index 000000000..2a640c3a3 --- /dev/null +++ b/docs/layouts/docs/baseof.html @@ -0,0 +1,35 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+ + +
+ {{ partial "version-banner.html" . }} + {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} + {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + \ No newline at end of file diff --git a/docs/layouts/docs/baseof.print.html b/docs/layouts/docs/baseof.print.html new file mode 100644 index 000000000..e839aa946 --- /dev/null +++ b/docs/layouts/docs/baseof.print.html @@ -0,0 +1,25 @@ + + + + {{ partial "head.html" . }} + + +
+ {{ partial "navbar.html" . }} +
+
+
+
+
+ {{ block "main" . }}{{ end }} +
+
+
+ {{ partial "footer.html" . }} +
+ {{ partial "scripts.html" . }} + + diff --git a/docs/layouts/docs/list.html b/docs/layouts/docs/list.html new file mode 100644 index 000000000..9ba3e31e8 --- /dev/null +++ b/docs/layouts/docs/list.html @@ -0,0 +1,20 @@ +{{ define "main" }} +
+

{{ .Title }}

+ {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} +
+ {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
+ {{ .Content }} + {{ partial "section-index.html" . -}} + {{ partial "feedback.html" . -}} + {{ if (.Site.Config.Services.Disqus.Shortname) -}} +
+ {{- partial "disqus-comment.html" . -}} + {{ end -}} + {{ partial "page-meta-lastmod.html" . -}} +
+{{ end -}} diff --git a/docs/layouts/docs/list.print.html b/docs/layouts/docs/list.print.html new file mode 100644 index 000000000..1b0401588 --- /dev/null +++ b/docs/layouts/docs/list.print.html @@ -0,0 +1,3 @@ +{{ define "main" }} +{{ partial "print/render" . }} +{{ end }} diff --git a/docs/layouts/docs/single.html b/docs/layouts/docs/single.html new file mode 100644 index 000000000..49bb662ad --- /dev/null +++ b/docs/layouts/docs/single.html @@ -0,0 +1,3 @@ +{{ define "main" }} +{{ .Render "content" }} +{{ end }} diff --git a/docs/layouts/home.html b/docs/layouts/home.html new file mode 100644 index 000000000..0666aebfd --- /dev/null +++ b/docs/layouts/home.html @@ -0,0 +1,19 @@ +{{ define "main" }} +
+

{{ .Title }}

+ {{ with .Params.description }}
{{ . | markdownify }}
{{ end }} +
+ {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
+ {{ .Content }} + {{ partial "section-index.html" . -}} + {{ partial "feedback.html" . -}} + {{ if (.Site.Config.Services.Disqus.Shortname) -}} +
+ {{- partial "disqus-comment.html" . -}} + {{ end -}} +
+{{ end -}} diff --git a/docs/layouts/partials/breadcrumb.html b/docs/layouts/partials/breadcrumb.html new file mode 100644 index 000000000..d01224a2a --- /dev/null +++ b/docs/layouts/partials/breadcrumb.html @@ -0,0 +1,29 @@ +{{ $isSingle := true -}} +{{ with .Parent -}} + {{ $isSingle = .IsHome -}} +{{ end -}} + + +{{- define "breadcrumbnav" -}} + {{ if .p1.Parent -}} + {{ if not .p1.Parent.IsHome -}} + {{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) -}} + {{ end -}} + {{ else if not .p1.IsHome -}} + {{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) -}} + {{ end -}} + {{ $isActive := eq .p1 .p2 }} +
  • + {{ if $isActive -}} + {{ .p1.LinkTitle -}} + {{ else -}} + {{ .p1.LinkTitle }} + {{- end -}} +
    • +{{- end -}} diff --git a/docs/layouts/partials/community_links.html b/docs/layouts/partials/community_links.html new file mode 100644 index 000000000..4f0505ebc --- /dev/null +++ b/docs/layouts/partials/community_links.html @@ -0,0 +1,33 @@ +{{ $links := .Site.Params.links -}} + +
    +
    +

    {{ T "community_learn" }}

    +

    {{ T "community_using" . }}

    + {{ with index $links "user" -}} + {{ template "community-links-list" . -}} + {{ end }} +
    +
    +

    {{ T "community_develop" }}

    +

    {{ T "community_contribute" . }}

    + {{ with index $links "developer" -}} + {{ template "community-links-list" . -}} + {{ end }} +

    + {{ T "community_how_to" . }} + {{ T "community_guideline" }}. +

    +
    +
    + +{{ define "community-links-list" -}} + +{{- end }} diff --git a/docs/layouts/partials/disqus-comment.html b/docs/layouts/partials/disqus-comment.html new file mode 100644 index 000000000..f7406c484 --- /dev/null +++ b/docs/layouts/partials/disqus-comment.html @@ -0,0 +1,23 @@ +
    + +
    + + +
    diff --git a/docs/layouts/partials/favicons.html b/docs/layouts/partials/favicons.html new file mode 100644 index 000000000..69e7f053b --- /dev/null +++ b/docs/layouts/partials/favicons.html @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/docs/layouts/partials/featured-image.html b/docs/layouts/partials/featured-image.html new file mode 100644 index 000000000..156a53b70 --- /dev/null +++ b/docs/layouts/partials/featured-image.html @@ -0,0 +1,14 @@ +{{ $w := .w | default 480 }} +{{ $h := .h | default 180 }} +{{ $p := .p }} +{{ $class := .class | default "ms-3" }} +{{ $image := ($p.Resources.ByType "image").GetMatch "**featured*" }} +{{ with $image }} +{{ $image := .Fill (printf "%dx%d" $w $h ) }} +
    +Featured Image for {{ $p.Title }} +{{ with $image.Params.byline }} +
    {{ . | html }}
    +{{ end }} +
    +{{ end }} \ No newline at end of file diff --git a/docs/layouts/partials/feedback.html b/docs/layouts/partials/feedback.html new file mode 100644 index 000000000..438edc423 --- /dev/null +++ b/docs/layouts/partials/feedback.html @@ -0,0 +1,61 @@ +{{ if (and (not .Params.hide_feedback) (.Site.Params.ui.feedback.enable)) -}} +{{ with .Site.Params.ui.feedback -}} + +
    +

    {{- i18n "feedback_title" -}}

    +

    {{- i18n "feedback_question" -}}

    + + +

    + {{ .yes | safeHTML }} +

    +

    + {{ .no | safeHTML }} +

    +
    + +{{ end -}} +
    +{{ end -}} diff --git a/docs/layouts/partials/footer.html b/docs/layouts/partials/footer.html new file mode 100644 index 000000000..e69de29bb diff --git a/docs/layouts/partials/footer/center.html b/docs/layouts/partials/footer/center.html new file mode 100644 index 000000000..e69de29bb diff --git a/docs/layouts/partials/footer/copyright.html b/docs/layouts/partials/footer/copyright.html new file mode 100644 index 000000000..1370c5e1f --- /dev/null +++ b/docs/layouts/partials/footer/copyright.html @@ -0,0 +1,42 @@ +{{ $page := .Page -}} +{{ with .Site.Params.copyright -}} + {{ $fromYear := "" -}} + {{ $toYear := "" -}} + {{ $authors := "" -}} + {{ if reflect.IsMap . -}} + {{ $fromYear = .from_year -}} + {{ $toYear = .to_year -}} + {{ $authors = .authors -}} + {{ else -}} + {{ $authors = . -}} + {{ end -}} + + © + {{ with $fromYear -}} + {{ . }}– + {{- end -}} + {{ $toYear | default now.Year }} + + {{- $authors + | default (printf "%s Authors" ($.Site.Title | default "Site")) + | $page.RenderString -}} + + {{- /* Trim WS */ -}} + + + {{- with T "footer_all_rights_reserved" -}} + + {{- . -}} + + {{- end }} + +{{- else -}} + + {{ with .Site.Copyright -}} + {{/* For historical reasons we process this as HTML rather than markdown. */ -}} + + {{- . | safeHTML -}} + + {{- end -}} + +{{ end -}} diff --git a/docs/layouts/partials/footer/left.html b/docs/layouts/partials/footer/left.html new file mode 100644 index 000000000..ed9265f4c --- /dev/null +++ b/docs/layouts/partials/footer/left.html @@ -0,0 +1,5 @@ +{{ with .Site.Params.links -}} + {{ with index . "user" -}} + {{- partial "footer/links.html" . -}} + {{ end -}} +{{ end -}} diff --git a/docs/layouts/partials/footer/links.html b/docs/layouts/partials/footer/links.html new file mode 100644 index 000000000..0d84f4e1d --- /dev/null +++ b/docs/layouts/partials/footer/links.html @@ -0,0 +1,9 @@ + diff --git a/docs/layouts/partials/footer/right.html b/docs/layouts/partials/footer/right.html new file mode 100644 index 000000000..3afc3d274 --- /dev/null +++ b/docs/layouts/partials/footer/right.html @@ -0,0 +1,5 @@ +{{ with .Site.Params.links -}} + {{ with index . "developer" -}} + {{- partial "footer/links.html" . -}} + {{ end -}} +{{ end -}} diff --git a/docs/layouts/partials/head-css.html b/docs/layouts/partials/head-css.html new file mode 100644 index 000000000..af8310d88 --- /dev/null +++ b/docs/layouts/partials/head-css.html @@ -0,0 +1,39 @@ +{{ $scssMain := "scss/main.scss" -}} +{{ $css := resources.Get $scssMain + | toCSS (dict "enableSourceMap" (not hugo.IsProduction)) -}} +{{ $bsRtlCss := "vendor/bootstrap/dist/css/bootstrap.rtl.css" -}} +{{ $rtlCSS := "" -}} + +{{ if eq .Site.Language.LanguageDirection "rtl" -}} + {{ with resources.Get $bsRtlCss -}} + {{ $rtlCSS = . -}} + {{ else -}} + {{ $msg := printf "Resource not found: %s" $bsRtlCss -}} + {{ warnf $msg -}} + + {{ end -}} +{{ end -}} + +{{ if hugo.IsProduction -}} + {{ with $rtlCSS -}} + {{ $rtlCSS = . | postCSS | minify | fingerprint -}} + {{ end -}} + {{ $css = $css | postCSS | minify | fingerprint -}} + +{{- end -}} + +{{/* NOTE: when not in production, we don't apply `postCSS`. This makes it +snappier to develop in Chrome, but makes it look sub-optimal in other browsers. +*/ -}} + +{{ with $css -}} + +{{ else -}} + {{ errorf "Resource not found: %s" $scssMain -}} +{{ end -}} + +{{ with $rtlCSS -}} + +{{ end -}} + +{{- /**/ -}} diff --git a/docs/layouts/partials/head.html b/docs/layouts/partials/head.html new file mode 100644 index 000000000..b1470a357 --- /dev/null +++ b/docs/layouts/partials/head.html @@ -0,0 +1,65 @@ + + +{{ range .AlternativeOutputFormats -}} + +{{ end -}} + +{{ $outputFormat := partial "outputformat.html" . -}} +{{ if and hugo.IsProduction (ne $outputFormat "print") -}} + +{{ else -}} + +{{ end -}} + +{{ partialCached "favicons.html" . }} + + {{- if .IsHome -}} + {{ .Site.Title -}} + {{ else -}} + {{ with .Title }}{{ . }} | {{ end -}} + {{ .Site.Title -}} + {{ end -}} + + +{{ template "_internal/opengraph.html" . -}} +{{ template "_internal/schema.html" . -}} +{{ template "_internal/twitter_cards.html" . -}} +{{ partialCached "head-css.html" . "head-css-cache-key" -}} + +{{ if .Site.Params.offlineSearch -}} + +{{ end -}} + +{{ if .Site.Params.prism_syntax_highlighting -}} + +{{ end -}} + +{{ template "algolia/head" . -}} + +{{ partial "hooks/head-end.html" . -}} + +{{/* To comply with GDPR, cookie consent scripts places in head-end must execute before Google Analytics is enabled */ -}} +{{ if hugo.IsProduction -}} + {{ template "_internal/google_analytics.html" . -}} +{{ end -}} + +{{ define "algolia/head" -}} + +{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}} + +{{ end -}} + +{{ if ne .Site.Params.algolia_docsearch nil -}} +{{ warnf `Config 'params.algolia_docsearch' is deprecated: use 'params.search.algolia' + For details, see https://www.docsy.dev/docs/adding-content/search/#algolia-docsearch.` -}} +{{ end -}} + +{{ end -}} diff --git a/docs/layouts/partials/hooks/body-end.html b/docs/layouts/partials/hooks/body-end.html new file mode 100644 index 000000000..e69de29bb diff --git a/docs/layouts/partials/hooks/head-end.html b/docs/layouts/partials/hooks/head-end.html new file mode 100644 index 000000000..e69de29bb diff --git a/docs/layouts/partials/navbar-lang-selector.html b/docs/layouts/partials/navbar-lang-selector.html new file mode 100644 index 000000000..37ccc1139 --- /dev/null +++ b/docs/layouts/partials/navbar-lang-selector.html @@ -0,0 +1,12 @@ +{{/* Link directly to documentation etc., if possible. */ -}} +{{ $langPage := cond (gt (len .Translations) 0) . .Site.Home -}} +
    + + +
    \ No newline at end of file diff --git a/docs/layouts/partials/navbar-version-selector.html b/docs/layouts/partials/navbar-version-selector.html new file mode 100644 index 000000000..b994e2106 --- /dev/null +++ b/docs/layouts/partials/navbar-version-selector.html @@ -0,0 +1,14 @@ +
    + + +
    \ No newline at end of file diff --git a/docs/layouts/partials/navbar.html b/docs/layouts/partials/navbar.html new file mode 100644 index 000000000..4e7a19689 --- /dev/null +++ b/docs/layouts/partials/navbar.html @@ -0,0 +1,71 @@ +{{ $cover := and + (.HasShortcode "blocks/cover") + (not .Site.Params.ui.navbar_translucent_over_cover_disable) +-}} +{{ $baseURL := urls.Parse $.Site.Params.Baseurl -}} + + diff --git a/docs/layouts/partials/outputformat.html b/docs/layouts/partials/outputformat.html new file mode 100644 index 000000000..bd83f9657 --- /dev/null +++ b/docs/layouts/partials/outputformat.html @@ -0,0 +1,12 @@ +{{/* Return the current page outputformat */}} +{{ $alts := newScratch }} +{{ $format := "unknown" }} +{{ range .AlternativeOutputFormats }} + {{ $alts.Set .Name true }} +{{ end }} +{{ range .OutputFormats }} + {{ if not ($alts.Get .Name) }} + {{ $format = .Name }} + {{ end }} +{{ end }} +{{ return $format }} diff --git a/docs/layouts/partials/page-description.html b/docs/layouts/partials/page-description.html new file mode 100644 index 000000000..3529fbe61 --- /dev/null +++ b/docs/layouts/partials/page-description.html @@ -0,0 +1,11 @@ +{{ with .Description | plainify -}} + {{ . -}} +{{ else -}} + {{ if .IsPage -}} + {{ .Summary | plainify | chomp -}} + {{ else -}} + {{ with .Site.Params.description | plainify -}} + {{ . -}} + {{ end -}} + {{ end -}} +{{ end -}} diff --git a/docs/layouts/partials/page-meta-lastmod.html b/docs/layouts/partials/page-meta-lastmod.html new file mode 100644 index 000000000..c14ebfca5 --- /dev/null +++ b/docs/layouts/partials/page-meta-lastmod.html @@ -0,0 +1,10 @@ +{{ if and .GitInfo .Site.Params.github_repo -}} +
    + {{ T "post_last_mod" }} {{ .Lastmod.Format .Site.Params.time_format_default -}} + {{ with .GitInfo }}: {{/* Trim WS */ -}} + + {{- .Subject }} ({{ .AbbreviatedHash }}) {{- /* Trim WS */ -}} + + {{- end }} +
    +{{ end -}} diff --git a/docs/layouts/partials/page-meta-links.html b/docs/layouts/partials/page-meta-links.html new file mode 100644 index 000000000..cd0f90d07 --- /dev/null +++ b/docs/layouts/partials/page-meta-links.html @@ -0,0 +1,52 @@ +{{/* cSpell:ignore querify subdir */ -}} +{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} + +{{ if .File -}} +{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} +{{ $gh_repo := $.Param "github_repo" -}} +{{ $gh_url := $.Param "github_url" -}} +{{ $gh_subdir := $.Param "github_subdir" | default "" -}} +{{ $gh_project_repo := $.Param "github_project_repo" -}} +{{ $gh_branch := $.Param "github_branch" | default "main" -}} +
    +{{ if $gh_url -}} + {{ warnf "Warning: use of `github_url` is deprecated. For details, see https://www.docsy.dev/docs/adding-content/repository-links/#github_url-optional" -}} + {{ T "post_edit_this" }} +{{ else if $gh_repo -}} + + {{/* Adjust $path based on path_base_for_github_subdir */ -}} + {{ $ghs_base := $.Param "path_base_for_github_subdir" -}} + {{ $ghs_rename := "" -}} + {{ if reflect.IsMap $ghs_base -}} + {{ $ghs_rename = $ghs_base.to -}} + {{ $ghs_base = $ghs_base.from -}} + {{ end -}} + {{ with $ghs_base -}} + {{ $path = replaceRE . $ghs_rename $path -}} + {{ end -}} + + {{ $gh_repo_path := printf "%s/%s/%s" $gh_branch $gh_subdir $path -}} + {{ $gh_repo_path = replaceRE "//+" "/" $gh_repo_path -}} + + {{ $viewURL := printf "%s/blob/%s" $gh_repo $gh_repo_path -}} + {{ $editURL := printf "%s/edit/%s" $gh_repo $gh_repo_path -}} + {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}} + {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} + {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} + {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}} + + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} + {{ with $gh_project_repo -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} + {{ end -}} + +{{ end -}} +{{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} + {{ T "print_entire_section" }} +{{ end }} +
    +{{ end -}} diff --git a/docs/layouts/partials/pager.html b/docs/layouts/partials/pager.html new file mode 100644 index 000000000..f24a5c0df --- /dev/null +++ b/docs/layouts/partials/pager.html @@ -0,0 +1,8 @@ + diff --git a/docs/layouts/partials/print/content-blog.html b/docs/layouts/partials/print/content-blog.html new file mode 100644 index 000000000..724e74cfb --- /dev/null +++ b/docs/layouts/partials/print/content-blog.html @@ -0,0 +1,14 @@ +{{ $break := cond .DoPageBreak "page-break-before: always" "" }} +{{ with .Page }} +
    +

    {{ .Title }}

    + {{ with .Params.description }}
    {{ . | markdownify }}
    {{ end }} +
    + {{ with .Params.author }}{{ T "post_byline_by" }} {{ . | markdownify }} |{{ end}} + {{if .Date }} + + {{ end }} +
    + {{ .Content }} +
    +{{ end }} diff --git a/docs/layouts/partials/print/content.html b/docs/layouts/partials/print/content.html new file mode 100644 index 000000000..5e42cd183 --- /dev/null +++ b/docs/layouts/partials/print/content.html @@ -0,0 +1,13 @@ +{{ $tpl := printf "print/content-%s.html" .Page.Type }} + +{{ if templates.Exists (printf "partials/%s" $tpl) }} + {{ partial $tpl . }} +{{ else -}} +{{ $break := cond .DoPageBreak "page-break-before: always" "" -}} +
    + {{ $break := cond .DoPageBreak "page-break-before: always" "" }} +

    {{ .PageNum }} - {{ .Page.Title }}

    + {{ with .Page.Params.description }}
    {{ . | markdownify }}
    {{ end }} + {{ .Page.Content }} +
    +{{ end }} diff --git a/docs/layouts/partials/print/page-heading.html b/docs/layouts/partials/print/page-heading.html new file mode 100644 index 000000000..a0a2d6311 --- /dev/null +++ b/docs/layouts/partials/print/page-heading.html @@ -0,0 +1,9 @@ +{{/* Use the title and description of the first page to begin the document */}} + +{{ $tpl := printf "print/page-heading-%s.html" .Page.Type }} +{{ if templates.Exists (printf "partials/%s" $tpl) }} + {{ partial $tpl . }} +{{ else -}} +

    {{ .Title }}

    +{{ with .Page.Params.description }}
    {{ . | markdownify }}
    {{ end }} +{{ end }} diff --git a/docs/layouts/partials/print/render.html b/docs/layouts/partials/print/render.html new file mode 100644 index 000000000..77c315766 --- /dev/null +++ b/docs/layouts/partials/print/render.html @@ -0,0 +1,63 @@ +{{ define "recurse-toc" }} + {{ $s := .section }} + {{ $psid := .psid }} + {{ $pages := (union $s.Pages $s.Sections).ByWeight }} + {{ $subSection := 1 }} + + {{ range where $pages ".Params.no_print" "!=" true }} + {{ $sid := printf "%s%d" $psid $subSection }} + {{ $subSection = add $subSection 1 }} + {{ partial "print/toc-li.html" (dict "sid" $sid "Page" .) }} + {{ if .IsSection }} + + {{ end }} + {{ end }} +{{ end }} + +{{ define "recurse-content" }} + {{ $s := .section }} + {{ $psid := .psid }} + {{ $pages := (union $s.Pages $s.Sections).ByWeight }} + {{ $subSection := 1 }} + + {{ $breakOnWordCount := default 50 ($s.Site.Param "print.section_break_wordcount") }} + {{ $doPageBreak := gt (countwords $s.Content) $breakOnWordCount }} + + {{ range where $pages ".Params.no_print" "!=" true }} + {{ $sid := printf "%s%d" $psid $subSection }} + {{ $subSection = add $subSection 1 }} + {{ $params := dict "Page" . "PageNum" $sid "DoPageBreak" $doPageBreak }} + {{ partial "print/content.html" $params }} + + {{ if .IsSection }} + {{ template "recurse-content" (dict "section" . "psid" (printf "%s." $sid) ) }} + {{ end }} + {{ $doPageBreak = true }} + {{ end }} +{{ end }} + +
    +
    +

    +{{ T "print_printable_section" }} +{{ T "print_click_to_print" }}. +

    +{{ T "print_show_regular" }}. +

    +
    +{{ partial "print/page-heading.html" . }} + +{{ if not (.Param "print.disable_toc") }} + +{{ end }} + +
    + {{ .Content }} +
    +
    + +{{ template "recurse-content" (dict "section" .CurrentSection "psid" "") }} diff --git a/docs/layouts/partials/print/toc-li-blog.html b/docs/layouts/partials/print/toc-li-blog.html new file mode 100644 index 000000000..55aa7b8bc --- /dev/null +++ b/docs/layouts/partials/print/toc-li-blog.html @@ -0,0 +1 @@ +
  • {{ .Page.Title }}
    • diff --git a/docs/layouts/partials/print/toc-li.html b/docs/layouts/partials/print/toc-li.html new file mode 100644 index 000000000..27fbb5e44 --- /dev/null +++ b/docs/layouts/partials/print/toc-li.html @@ -0,0 +1,6 @@ +{{ $tpl := printf "print/toc-li-%s.html" .Page.Type }} +{{ if templates.Exists (printf "partials/%s" $tpl) }} + {{ partial $tpl . }} +{{ else -}} +
  • {{ .sid}}: {{ .Page.Title }}
    • +{{ end }} diff --git a/docs/layouts/partials/reading-time.html b/docs/layouts/partials/reading-time.html new file mode 100644 index 000000000..454f2f0a7 --- /dev/null +++ b/docs/layouts/partials/reading-time.html @@ -0,0 +1 @@ +

     {{ if gt .ReadingTime 1 }} {{ .ReadingTime }} {{ T "post_reading_time" }} {{ else }} {{ T "post_less_than_a_minute_read" }} {{ end }} 

    diff --git a/docs/layouts/partials/scripts.html b/docs/layouts/partials/scripts.html new file mode 100644 index 000000000..a9b2d32c4 --- /dev/null +++ b/docs/layouts/partials/scripts.html @@ -0,0 +1,121 @@ +{{ $needKaTeX := or .Site.Params.katex.enable .Params.math .Params.chem -}} +{{ $needmhchem := or .Site.Params.katex.mhchem.enable .Params.chem -}} +{{ if ge hugo.Version "0.93.0" -}} + {{ $needKaTeX = or $needKaTeX (.Page.Store.Get "hasKaTeX") (.Page.Store.Get "hasmhchem") -}} + {{ $needmhchem = or $needmhchem (.Page.Store.Get "hasmhchem") -}} +{{ else -}} + {{ if or $needKaTeX $needmhchem -}} + {{ warnf "Outdated Hugo version %s, consider upgrading to make full use of all theme features" hugo.Version }} + {{ end -}} +{{ end -}} + +{{ if .Site.Params.markmap.enable -}} + + + +{{ end -}} + +{{ if .Site.Params.plantuml.enable -}} + +{{ end -}} + +{{ if $needKaTeX -}} +{{/* load stylesheet and scripts for KaTeX support */ -}} + + {{/* The loading of KaTeX is deferred to speed up page rendering */ -}} + + {{ if $needmhchem -}} + {{/* To add support for displaying chemical equations and physical units, load the mhchem extension: */ -}} + + {{ end -}} + {{/* To automatically render math in text elements, include the auto-render extension: */ -}} + +{{ end -}} + +{{ $jsBs := resources.Get "vendor/bootstrap/dist/js/bootstrap.bundle.js" -}} +{{ $jsBase := resources.Get "js/base.js" -}} +{{ $jsSearch := resources.Get "js/search.js" | resources.ExecuteAsTemplate "js/search.js" .Site.Home -}} +{{ $jsMarkmap := resources.Get "js/markmap.js" | resources.ExecuteAsTemplate "js/markmap.js" . -}} +{{ $jsPlantuml := resources.Get "js/plantuml.js" | resources.ExecuteAsTemplate "js/plantuml.js" . -}} +{{ $jsDrawio := resources.Get "js/drawio.js" | resources.ExecuteAsTemplate "js/drawio.js" . -}} +{{ if .Site.Params.offlineSearch -}} + {{ $jsSearch = resources.Get "js/offline-search.js" -}} +{{ end -}} + +{{ $jsArray := slice $jsBs $jsBase $jsSearch $jsPlantuml $jsMarkmap $jsDrawio -}} + +{{ if .Page.Store.Get "hasmermaid" -}} +{{- partial "scripts/mermaid.html" . -}} +{{ end -}} + +{{ if .Site.Params.ui.showLightDarkModeMenu -}} + {{ $jsArray = $jsArray | append (resources.Get "js/dark-mode.js") -}} +{{ end -}} + +{{ $js := $jsArray | resources.Concat "js/main.js" -}} +{{ if hugo.IsProduction -}} + {{ $js := $js | minify | fingerprint -}} + +{{ else -}} + +{{ end -}} + +{{ if .Site.Params.prism_syntax_highlighting -}} + +{{ else if ( not .Site.Params.disable_click2copy_chroma ) -}} + {{ $c2cJS := resources.Get "js/click-to-copy.js" -}} + {{ if hugo.IsProduction -}} + {{ $c2cJS = $c2cJS | minify | fingerprint -}} + {{ end -}} + +{{ end -}} + +{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}} + {{ template "algolia/scripts" .Site.Params.search.algolia -}} +{{ end -}} + +{{ partial "hooks/body-end.html" . -}} + +{{ define "algolia/scripts" -}} + + +{{ end -}} diff --git a/docs/layouts/partials/scripts/mermaid.html b/docs/layouts/partials/scripts/mermaid.html new file mode 100644 index 000000000..62e8c072c --- /dev/null +++ b/docs/layouts/partials/scripts/mermaid.html @@ -0,0 +1,67 @@ +{{ $version := .Site.Params.mermaid.version | default "latest" -}} + +{{ $cdnurl := printf "https://cdn.jsdelivr.net/npm/mermaid@%s/dist/mermaid.esm.min.mjs" $version -}} +{{ with resources.GetRemote $cdnurl -}} + {{ with .Err -}} + {{ errorf "Could not retrieve mermaid script from CDN. Reason: %s." . -}} + {{ end -}} +{{ else -}} + {{ errorf "Invalid Mermaid version %s, could not retrieve this version from CDN." $version -}} +{{ end -}} + + diff --git a/docs/layouts/partials/search-input.html b/docs/layouts/partials/search-input.html new file mode 100644 index 000000000..7817e0abc --- /dev/null +++ b/docs/layouts/partials/search-input.html @@ -0,0 +1,61 @@ +{{ .Scratch.Set "docsy-search" 0 -}} + +{{ if .Site.Params.gcs_engine_id -}} +{{ .Scratch.Add "docsy-search" 1 -}} + +
    +
    + +
    + +{{- end -}} + + +{{ if and .Site.Params.search (isset .Site.Params.search "algolia") -}} +{{ .Scratch.Add "docsy-search" 1 -}} +{{ .Scratch.Add "docsearch-id-num" 1 -}} + +
    +
    +
    + +{{- end -}} + + +{{ if .Site.Params.offlineSearch -}} +{{ .Scratch.Add "docsy-search" 1 -}} + +{{ $offlineSearchIndex := resources.Get "json/offline-search-index.json" | resources.ExecuteAsTemplate "offline-search-index.json" . -}} +{{ if hugo.IsProduction -}} +{{/* Use `md5` as finger print hash function to shorten file name to avoid `file name too long` error. */ -}} +{{ $offlineSearchIndex = $offlineSearchIndex | fingerprint "md5" -}} +{{ end -}} +{{ $offlineSearchLink := $offlineSearchIndex.RelPermalink -}} + +
    +
    + +
    + +{{- end -}} + +{{ if gt (.Scratch.Get "docsy-search") 1 -}} +{{ warnf `You have more than one site-search option configured: choose only one. + For details, see https://www.docsy.dev/docs/adding-content/search.` -}} +{{ end -}} diff --git a/docs/layouts/partials/section-index.html b/docs/layouts/partials/section-index.html new file mode 100644 index 000000000..bf0a21006 --- /dev/null +++ b/docs/layouts/partials/section-index.html @@ -0,0 +1,36 @@ +
    + {{ $page := .Page -}} + {{ $pages := (where .Site.Pages "Section" .Section).ByWeight -}} + {{ $pages = (where $pages "Type" "!=" "search") }} + {{ $pages = (where $pages ".Params.hide_summary" "!=" true) -}} + {{ $pages = (where $pages ".Parent" "!=" nil) -}} + {{ $pages = (where $pages ".Parent.File" "!=" nil) -}} + {{ if $page.File -}} + {{ $pages = (where $pages "Parent.File.UniqueID" "==" $page.File.UniqueID) -}} + {{ end -}} + {{ if or $page.Params.no_list (eq (len $pages) 0) -}} + {{/* If no_list is true or we don't have subpages we don't show a list of subpages */}} + {{ else if $page.Params.simple_list -}} + {{/* If simple_list is true we show a bulleted list of subpages */}} + + {{ else -}} + {{/* Otherwise we show a nice formatted list of subpages with page descriptions */}} +
    + {{ range $pages -}} + {{ $manualLink := cond (isset .Params "manuallink") .Params.manualLink ( cond (isset .Params "manuallinkrelref") (relref . .Params.manualLinkRelref) .RelPermalink) -}} + {{ if ne .File.Path "search.md" }} +
    +
    + {{- .Title -}} +
    +

    {{ .Description | markdownify -}}

    +
    + {{ end -}} + {{ end -}} + {{ end -}} +
    diff --git a/docs/layouts/partials/sidebar-tree.html b/docs/layouts/partials/sidebar-tree.html new file mode 100644 index 000000000..ba126c381 --- /dev/null +++ b/docs/layouts/partials/sidebar-tree.html @@ -0,0 +1,76 @@ +{{/* We cache this partial for bigger sites and set the active class client side. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} +{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}} +
    + {{ if not .Site.Params.ui.sidebar_search_disable -}} +
    + {{ partial "search-input.html" . }} + +
    + {{ else -}} +
    +
    + {{ partial "search-input.html" . }} + +
    +
    +
    + {{ end -}} + +
    +{{ define "section-tree-nav-section" -}} +{{ $s := .section -}} +{{ $p := .page -}} +{{ $shouldDelayActive := .shouldDelayActive -}} +{{ $sidebarMenuTruncate := .sidebarMenuTruncate -}} +{{ $treeRoot := cond (eq .ulNr 0) true false -}} +{{ $ulNr := .ulNr -}} +{{ $ulShow := .ulShow -}} +{{ $active := and (not $shouldDelayActive) (eq $s $p) -}} +{{ $activePath := and (not $shouldDelayActive) (or (eq $p $s) ($p.IsDescendant $s)) -}} +{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}} +{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}} +{{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}} +{{ $pages := $pages_tmp | first $sidebarMenuTruncate -}} +{{ $withChild := gt (len $pages) 0 -}} +{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}} +{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}} +{{ if ne $s.File.Path "search.md" }} +
  • + {{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}} + + + {{ else -}} + {{ with $s.Params.Icon}}{{ end }}{{ $s.LinkTitle }} + {{- end }} + {{- if $withChild }} + {{- $ulNr := add $ulNr 1 }} + + {{- end }} +
    • +{{- end }} +{{- end }} \ No newline at end of file diff --git a/docs/layouts/partials/sidebar.html b/docs/layouts/partials/sidebar.html new file mode 100644 index 000000000..83e149f30 --- /dev/null +++ b/docs/layouts/partials/sidebar.html @@ -0,0 +1,23 @@ +{{/* The "active" toggle here may delay rendering, so we only cache this side bar menu for bigger sites. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} +{{ $shouldCache := ge (len .Site.Pages) $sidebarCacheLimit -}} +{{ $sidebarCacheTypeRoot := .Site.Params.ui.sidebar_cache_type_root | default false -}} +{{ if $shouldCache -}} + {{ $mid := printf "m-%s" (.RelPermalink | anchorize) }} + + {{ partialCached "sidebar-tree.html" . .FirstSection.RelPermalink }} +{{ else -}} + {{ partial "sidebar-tree.html" . }} +{{- end }} \ No newline at end of file diff --git a/docs/layouts/partials/taxonomy_terms_article.html b/docs/layouts/partials/taxonomy_terms_article.html new file mode 100644 index 000000000..79ef364f7 --- /dev/null +++ b/docs/layouts/partials/taxonomy_terms_article.html @@ -0,0 +1,12 @@ +{{ $context := .context -}} +{{ $taxo := .taxo -}} +{{ if (gt (len ($context.GetTerms $taxo)) 0) -}} +
    +
    {{ humanize $taxo }}:
    + +
    +{{ end -}} diff --git a/docs/layouts/partials/taxonomy_terms_article_wrapper.html b/docs/layouts/partials/taxonomy_terms_article_wrapper.html new file mode 100644 index 000000000..a99ffc359 --- /dev/null +++ b/docs/layouts/partials/taxonomy_terms_article_wrapper.html @@ -0,0 +1,16 @@ +{{ $context := . -}} +{{ if .Site.Params.Taxonomy -}} + {{ if .Site.Params.Taxonomy.taxonomyPageHeader -}} + {{ range $index, $taxo := .Site.Params.Taxonomy.taxonomyPageHeader -}} + {{ partial "taxonomy_terms_article.html" (dict "context" $context "taxo" $taxo) -}} + {{ end }} + {{ else -}} + {{ range $taxo, $taxo_map := .Site.Taxonomies -}} + {{ partial "taxonomy_terms_article.html" (dict "context" $context "taxo" $taxo) -}} + {{ end }} + {{ end -}} +{{ else -}} + {{ range $taxo, $taxo_map := .Site.Taxonomies -}} + {{ partial "taxonomy_terms_article.html" (dict "context" $context "taxo" $taxo) -}} + {{ end }} +{{ end -}} diff --git a/docs/layouts/partials/taxonomy_terms_cloud.html b/docs/layouts/partials/taxonomy_terms_cloud.html new file mode 100644 index 000000000..43656f5ed --- /dev/null +++ b/docs/layouts/partials/taxonomy_terms_cloud.html @@ -0,0 +1,18 @@ +{{ $context := .context -}} +{{ $taxo := .taxo -}} +{{ $title := .title -}} +{{ if isset $context.Site.Taxonomies (lower $taxo) -}} + {{ $taxonomy := index $context.Site.Taxonomies (lower $taxo) -}} + {{ if (gt (len $taxonomy) 0) -}} +
    + {{ with $title -}} +
    {{ . }}
    + {{ end -}} + +
    + {{ end -}} +{{ end -}} diff --git a/docs/layouts/partials/taxonomy_terms_clouds.html b/docs/layouts/partials/taxonomy_terms_clouds.html new file mode 100644 index 000000000..1588fb26d --- /dev/null +++ b/docs/layouts/partials/taxonomy_terms_clouds.html @@ -0,0 +1,21 @@ +{{ $context := . -}} +{{ if .Site.Params.taxonomy -}} + {{ if .Site.Params.Taxonomy.taxonomyCloud -}} + {{ range $index, $taxo := .Site.Params.Taxonomy.taxonomyCloud -}} + {{ if $.Site.Params.Taxonomy.taxonomyCloudTitle -}} + {{ $.Scratch.Set "title" (index $.Site.Params.Taxonomy.taxonomyCloudTitle $index) -}} + {{ else -}} + {{ $.Scratch.Set "title" (humanize $taxo) -}} + {{ end -}} + {{ partial "taxonomy_terms_cloud.html" (dict "context" $context "taxo" $taxo "title" ($.Scratch.Get "title")) -}} + {{ end }} + {{ else -}} + {{ range $taxo, $taxo_map := .Site.Taxonomies -}} + {{ partial "taxonomy_terms_cloud.html" (dict "context" $context "taxo" $taxo "title" (humanize $taxo)) -}} + {{ end }} + {{ end -}} +{{ else -}} + {{ range $taxo, $taxo_map := .Site.Taxonomies -}} + {{ partial "taxonomy_terms_cloud.html" (dict "context" $context "taxo" $taxo "title" (humanize $taxo)) -}} + {{ end }} +{{ end -}} diff --git a/docs/layouts/partials/theme-toggler.html b/docs/layouts/partials/theme-toggler.html new file mode 100644 index 000000000..f954f8bf5 --- /dev/null +++ b/docs/layouts/partials/theme-toggler.html @@ -0,0 +1,59 @@ +{{/* Adapted from: https://github.com/twbs/bootstrap/blob/main/site/layouts/partials/icons.html */ -}} + + + + + + + + + + + + + + + + + +{{/* Adapted from: https://github.com/twbs/bootstrap/blob/main/site/layouts/partials/theme-toggler.html */ -}} + +{{ $isExamples := eq .Layout "examples" -}} + + diff --git a/docs/layouts/partials/toc.html b/docs/layouts/partials/toc.html new file mode 100644 index 000000000..36185b799 --- /dev/null +++ b/docs/layouts/partials/toc.html @@ -0,0 +1,9 @@ +{{ if not .Params.notoc -}} + {{ with .TableOfContents -}} + {{ if ne . `` -}} +
    + {{ . }} +
    + {{ end -}} + {{ end -}} +{{ end -}} diff --git a/docs/layouts/partials/version-banner.html b/docs/layouts/partials/version-banner.html new file mode 100644 index 000000000..6bfbc466e --- /dev/null +++ b/docs/layouts/partials/version-banner.html @@ -0,0 +1,16 @@ + + {{ if .Site.Params.archived_version }} + {{ $color := "primary" }} + {{ $latest_version := .Site.Params.url_latest_version }} + {{ $current_version := .Site.Params.version }} +
    + {{ with $current_version }}

    Version {{ . | markdownify }} of the + documentation is no longer actively maintained. The site that you are + currently viewing is an archived snapshot. + {{ with $latest_version }}For up-to-date documentation, see the + latest version.

    + {{ end }} + {{ end }} +
    +{{ end }} diff --git a/docs/layouts/shortcodes/alert.html b/docs/layouts/shortcodes/alert.html new file mode 100644 index 000000000..12804b7a8 --- /dev/null +++ b/docs/layouts/shortcodes/alert.html @@ -0,0 +1,10 @@ +{{ $_hugo_config := `{ "version": 1 }` }} +{{ $color := .Get "color" | default "primary" }} + diff --git a/docs/layouts/shortcodes/blocks/cover.html b/docs/layouts/shortcodes/blocks/cover.html new file mode 100644 index 000000000..8779b3452 --- /dev/null +++ b/docs/layouts/shortcodes/blocks/cover.html @@ -0,0 +1,54 @@ +{{ $_hugo_config := `{ "version": 1 }` -}} +{{ $blockID := printf "td-cover-block-%d" .Ordinal -}} +{{ $promo_image := (.Page.Resources.ByType "image").GetMatch "**background*" -}} +{{ $logo_image := (.Page.Resources.ByType "image").GetMatch "**logo*" -}} +{{ $col_id := .Get "color" | default "dark" -}} +{{ $image_anchor := .Get "image_anchor" | default "smart" -}} +{{ $logo_anchor := .Get "logo_anchor" | default "smart" -}} +{{/* Height can be one of: auto, min, med, max, full. */ -}} +{{ $height := .Get "height" | default "max" -}} + +{{ with $promo_image -}} +{{ $promo_image_big := . -}} +{{ $promo_image_small := . -}} +{{ if ne $promo_image.MediaType.SubType "svg" -}} + {{ $promo_image_big = .Fill (printf "1920x1080 %s" $image_anchor) -}} + {{ $promo_image_small = .Fill (printf "960x540 %s" $image_anchor) -}} +{{ end -}} + + + +{{ end -}} + +
    +
    +
    +
    + {{ with .Get "title" }}

    {{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}{{ end }}{{ $title | html }}

    {{ end }} + {{ with .Get "subtitle" }}

    {{ . | html }}

    {{ end }} +
    + {{ if eq .Page.File.Ext "md" }} + {{ .Inner | markdownify }} + {{ else }} + {{ .Inner | htmlUnescape | safeHTML }} + {{ end }} +
    +
    +
    +
    + {{ with .Get "byline" | default "" -}} +
    {{ . }}
    + {{- end }} +
    +{{/**/ -}} diff --git a/docs/layouts/shortcodes/blocks/feature.html b/docs/layouts/shortcodes/blocks/feature.html new file mode 100644 index 000000000..bdda3f452 --- /dev/null +++ b/docs/layouts/shortcodes/blocks/feature.html @@ -0,0 +1,13 @@ +{{ $icon := .Get "icon" | default "fa-lightbulb" -}} +
    +
    + +
    +

    + {{- .Get "title" | markdownify -}} +

    +
    +{{ .Inner }} +
    +{{ with .Get "url" }}

    {{ with $.Get "url_text" }}{{ . }}{{ else }}{{ T "ui_read_more" }}{{ end }}

    {{ end }} +
    diff --git a/docs/layouts/shortcodes/blocks/lead.html b/docs/layouts/shortcodes/blocks/lead.html new file mode 100644 index 000000000..4c0582533 --- /dev/null +++ b/docs/layouts/shortcodes/blocks/lead.html @@ -0,0 +1,20 @@ +{{ $col_id := .Get "color" | default .Ordinal -}} +{{ $height := .Get "height" | default "auto" -}} +{{ with .Get "height" -}} + {{ if not ( or ( eq . "auto" ) ( eq . "min" ) ( eq . "med" ) ( eq . "max" ) ( eq . "full" ) ) -}} + {{ errorf "shortcode 'lead': parameter height is %q, must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}} + {{ end -}} +{{ end -}} + +
    +
    +
    +
    +
    +{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} +{{ .Inner }} +
    +
    +
    +
    +{{/**/ -}} diff --git a/docs/layouts/shortcodes/blocks/link-down.html b/docs/layouts/shortcodes/blocks/link-down.html new file mode 100644 index 000000000..03e3003a3 --- /dev/null +++ b/docs/layouts/shortcodes/blocks/link-down.html @@ -0,0 +1,7 @@ +{{ with .Parent }} +{{ $id := $.Get "id" | default (printf "td-block-%d" ( add .Ordinal 1 )) }} +{{ $color := $.Get "color" | default "blue" }} + +{{ else }} +{{ errorf "The link-down shortcode is supposed to be nested inside a shortcode"}} +{{ end }} \ No newline at end of file diff --git a/docs/layouts/shortcodes/blocks/section.html b/docs/layouts/shortcodes/blocks/section.html new file mode 100644 index 000000000..29f2e79e0 --- /dev/null +++ b/docs/layouts/shortcodes/blocks/section.html @@ -0,0 +1,14 @@ +{{ $col_id := .Get "color" | default .Ordinal -}} +{{ $height := .Get "height" | default "auto" -}} +{{ $type := .Get "type" | default "container" -}} + +
    +
    +
    +
    +{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} +{{ .Inner -}} +
    +
    +
    +{{/**/ -}} diff --git a/docs/layouts/shortcodes/card.html b/docs/layouts/shortcodes/card.html new file mode 100644 index 000000000..83db94b3a --- /dev/null +++ b/docs/layouts/shortcodes/card.html @@ -0,0 +1,47 @@ +{{/* Check parameter type */ -}} +{{ $code := false -}} +{{ with .Get "code" -}} + {{ $type := printf "%T" . -}} + {{ if ne $type "bool" -}} + {{ errorf `shortcode 'card': boolean value expected for parameter 'code', but got %s` $type -}} + {{ else }} + {{ $code = . -}} + {{ end -}} +{{ end -}} + +{{ $lang := default "" (.Get "lang") -}} +{{ $highlight := default "" (.Get "highlight") -}} + +
    +{{ with $.Get "header" -}} +
    + {{ . | markdownify }} +
    +{{ end -}} +
    + {{ with $.Get "title" -}} +
    + {{ . | markdownify -}} +
    + {{ end -}} + {{ with $.Get "subtitle" -}} +
    + {{ . | markdownify -}} +
    + {{ end -}} + {{ with $.Inner -}} + {{ if $code -}} + {{ highlight . $lang $highlight -}} + {{ else -}} +

    + {{ . -}} +

    + {{ end -}} + {{ end -}} +
    + {{ with $.Get "footer" -}} +
    + {{ . | markdownify -}} +
    + {{ end -}} +
    diff --git a/docs/layouts/shortcodes/cardpane.html b/docs/layouts/shortcodes/cardpane.html new file mode 100644 index 000000000..caa3f8b66 --- /dev/null +++ b/docs/layouts/shortcodes/cardpane.html @@ -0,0 +1,3 @@ +
    +{{- .Inner -}} +
    diff --git a/docs/layouts/shortcodes/conditional-text.html b/docs/layouts/shortcodes/conditional-text.html new file mode 100644 index 000000000..ee7b2308e --- /dev/null +++ b/docs/layouts/shortcodes/conditional-text.html @@ -0,0 +1,36 @@ + +{{- $condition := lower $.Site.Params.buildCondition -}} + +{{- if ne $condition "" -}} + + + {{- $include_if := lower (.Get "include-if") -}} + {{- $exclude_if := lower (.Get "exclude-if") -}} + + {{- if and (in $include_if $condition) (in $exclude_if $condition) -}} + + {{- errorf "Build condition %q appears in both include-if and exclude-if parameters of conditional-txt shortcode on page %s" $condition .Position -}} + {{- end -}} + + {{- if isset $.Params "include-if" -}} + + {{- if in $include_if $condition -}} + +{{- .Inner -}} + {{- else -}} + {{- end -}} + {{- else -}} + + {{- if isset $.Params "exclude-if" -}} + + {{- if in $exclude_if $condition -}} + {{- else -}} + +{{- .Inner -}} + {{- end -}} + {{- end -}} + + {{- end -}} + +{{- end -}} diff --git a/docs/layouts/shortcodes/figure.html b/docs/layouts/shortcodes/figure.html new file mode 100644 index 000000000..8d126f065 --- /dev/null +++ b/docs/layouts/shortcodes/figure.html @@ -0,0 +1,29 @@ +{{ $src := (.Page.Resources.GetMatch (printf "**%s*" (.Get "src"))) }} + + {{- if .Get "link" -}} + + {{- end }} + {{ with .Get + {{- if .Get "link" }}{{ end -}} + {{- if or (or (.Get "title") (.Get "caption")) (.Get "attr") -}} +
    + {{ with (.Get "title") -}} +

    {{ . }}

    + {{- end -}} + {{- if or (.Get "caption") (.Get "attr") -}}

    + {{- .Get "caption" | markdownify -}} + {{- with .Get "attrlink" }} + + {{- end -}} + {{- .Get "attr" | markdownify -}} + {{- if .Get "attrlink" }}{{ end }}

    + {{- end }} +
    + {{- end }} + diff --git a/docs/layouts/shortcodes/iframe.html b/docs/layouts/shortcodes/iframe.html new file mode 100644 index 000000000..38ab12c6d --- /dev/null +++ b/docs/layouts/shortcodes/iframe.html @@ -0,0 +1,21 @@ +{{ $src := .Get "src" | }} +{{ $width := .Get "width" | default "100%" }} +{{ $tryautoheight := .Get "tryautoheight" | default true }} +{{ $style := .Get "style" | default "min-height:98vh; border:none;" }} +{{ $sandbox := .Get "sandbox" | default false }} +{{ $name := .Get "name" | default "iframe-name" }} +{{ $id := .Get "id" | default "iframe-id" }} +{{ $class := .Get "class" }} +{{ $sub := .Get "sub" | default "Your browser can not display embedded frames. You can access the embedded page via the following link:" }} +{{ with $src }} +{{ if $tryautoheight }} + +{{ end }} + +{{ end }} \ No newline at end of file diff --git a/docs/layouts/shortcodes/imgproc.html b/docs/layouts/shortcodes/imgproc.html new file mode 100644 index 000000000..ceeb2d02a --- /dev/null +++ b/docs/layouts/shortcodes/imgproc.html @@ -0,0 +1,27 @@ +{{ $original := .Page.Resources.GetMatch (printf "**%s*" (.Get 0)) -}} +{{ $command := .Get 1 -}} +{{ $options := .Get 2 -}} +{{ if eq $command "Fit" -}} + {{ .Scratch.Set "image" ($original.Fit $options) -}} +{{ else if eq $command "Resize" -}} + {{ .Scratch.Set "image" ($original.Resize $options) -}} +{{ else if eq $command "Fill" -}} + {{ .Scratch.Set "image" ($original.Fill $options) -}} +{{ else if eq $command "Crop" -}} + {{ .Scratch.Set "image" ($original.Crop $options) -}} +{{ else -}} + {{ errorf "Invalid image processing command: Must be one of Fit, Fill, Crop or Resize." -}} +{{ end -}} +{{ $image := .Scratch.Get "image" -}} + +
    + +{{ with .Inner -}} +
    +

    +{{/* Do **not** remove this comment! It ends above html block! See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} +{{ . }}{{ with $image.Params.byline }}
    {{ . }}    {{ end }} +

    +
    +{{ end -}} +
    diff --git a/docs/layouts/shortcodes/pageinfo.html b/docs/layouts/shortcodes/pageinfo.html new file mode 100644 index 000000000..303f8c5fd --- /dev/null +++ b/docs/layouts/shortcodes/pageinfo.html @@ -0,0 +1,5 @@ +{{ $_hugo_config := `{ "version": 1 }` }} +{{ $color := .Get "color" | default "primary" }} +
    +{{ .Inner }} +
    diff --git a/docs/layouts/shortcodes/readfile.html b/docs/layouts/shortcodes/readfile.html new file mode 100644 index 000000000..0a9b5a95a --- /dev/null +++ b/docs/layouts/shortcodes/readfile.html @@ -0,0 +1,41 @@ +{{/* Store ordinal, to be retrieved by parent element */}} +{{ if ge hugo.Version "0.93.0" }} + {{ .Page.Store.Add "Ordinal" 1 }} +{{ end }} + +{{/* Handle the "file" named parameter or a single unnamed parameter as the file +path */}} +{{ if .IsNamedParams }} + {{ $.Scratch.Set "fparameter" ( .Get "file" ) }} +{{ else }} + {{ $.Scratch.Set "fparameter" ( .Get 0 ) }} +{{ end }} + + +{{/* If the first character is "/", the path is absolute from the site's +`baseURL`. Otherwise, construct an absolute path using the current directory */}} + +{{ if eq (.Scratch.Get "fparameter" | printf "%.1s") "/" }} + {{ $.Scratch.Set "filepath" ($.Scratch.Get "fparameter") }} +{{ else }} + {{ $.Scratch.Set "filepath" "/" }} + {{ $.Scratch.Add "filepath" $.Page.File.Dir }} + {{ $.Scratch.Add "filepath" ($.Scratch.Get "fparameter") }} +{{ end }} + + +{{/* If the file exists, read it and highlight it if it's code. +Throw a compile error or print an error on the page if the file is not found */}} + +{{ if fileExists ($.Scratch.Get "filepath") }} + {{ if eq (.Get "code") "true" }} + {{- highlight ($.Scratch.Get "filepath" | readFile | htmlUnescape | + safeHTML ) (.Get "lang") "" -}} + {{ else }} + {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}} + {{ end }} +{{ else if eq (.Get "draft") "true" }} + +

    The file {{ $.Scratch.Get "filepath" }} was not found.

    + +{{ else }}{{- errorf "Shortcode %q: file %q not found at %s" .Name ($.Scratch.Get "filepath") .Position -}}{{ end }} diff --git a/docs/layouts/shortcodes/redoc.html b/docs/layouts/shortcodes/redoc.html new file mode 100644 index 000000000..0d4cf09d8 --- /dev/null +++ b/docs/layouts/shortcodes/redoc.html @@ -0,0 +1,91 @@ +{{- $file := .Get 0 -}} +{{- $url := "" -}} +{{- $otheroptions := .Get 1 -}} + +{{ if hasPrefix $file "http"}} + {{- $url = $file -}} +{{ else }} + {{ if (fileExists (print .Page.File.Dir $file)) -}} + + {{- $url = (print .Page.Site.BaseURL .Page.File.Dir $file) -}} + {{ else }} + + {{- $url = (print .Page.Site.BaseURL $file) -}} + {{- end }} +{{- end -}} + + + + + + + + + + + + + + +
    + +
    + + diff --git a/docs/layouts/shortcodes/swaggerui.html b/docs/layouts/shortcodes/swaggerui.html new file mode 100644 index 000000000..ea9b17c08 --- /dev/null +++ b/docs/layouts/shortcodes/swaggerui.html @@ -0,0 +1,15 @@ +{{ $original := .Get "src" }} +
    + diff --git a/docs/layouts/shortcodes/tab.html b/docs/layouts/shortcodes/tab.html new file mode 100644 index 000000000..561659649 --- /dev/null +++ b/docs/layouts/shortcodes/tab.html @@ -0,0 +1,55 @@ +{{- /* Make sure that we are enclosed within a tabpane shortcode block */ -}} + +{{ with $.Parent -}} + {{ if ne $.Parent.Name "tabpane" -}} + {{ errorf "Found shortcode %q enclosed inside a %q block, must be enclosed inside a %q block. Error position: %s" $.Name $.Parent.Name "tabpane" $.Position -}} + {{ end -}} +{{ else -}} + {{ errorf "shortcode %q must be enclosed inside a %q block, but no parent block was found. Error position: %s" $.Name "tabpane" $.Position -}} +{{ end -}} + +{{ $header := "Tab" -}} +{{ if and (not .IsNamedParams) (.Get 0) -}} + {{ $header = (.Get 0) -}} +{{ else -}} + {{/* Prefill header if not given as named or unnamed parameter */ -}} + {{ $header = .Get "header" | default (printf "Tab %v" .Ordinal) -}} +{{ end -}} + +{{/* store all tab info in dict tab */ -}} +{{ $tab := dict "header" $header -}} +{{ with $.Get "lang" -}} + {{ $tab = merge $tab (dict "language" .) -}} +{{ end -}} +{{ with $.Get "highlight" -}} + {{ $tab = merge $tab (dict "highlight" .) -}} +{{ end -}} +{{ with $.Get "text" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "text" (printf "%T" .) $.Position -}} + {{ end -}} + {{ $tab = merge $tab (dict "text" .) -}} +{{ end -}} +{{ with $.Get "right" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "right" (printf "%T" .) $.Position -}} + {{ end -}} + {{ $tab = merge $tab (dict "rightpush" .) -}} +{{ end -}} +{{ with $.Get "disabled" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "disabled" (printf "%T" .) $.Position -}} + {{ end -}} + {{ $tab = merge $tab (dict "disabled" .) -}} +{{ end -}} + +{{ with $.Inner -}} + {{/* Trim any leading and trailing newlines from .Inner, this avoids + spurious lines during syntax highlighting */ -}} + {{ $tab = merge $tab (dict "content" .) -}} +{{ end -}} + +{{/* add dict tab to parent's scratchpad */ -}} +{{ with .Parent -}} + {{ $.Parent.Scratch.SetInMap "tabs" (printf "%02v" $.Ordinal) $tab -}} +{{ end -}} diff --git a/docs/layouts/shortcodes/tabpane.html b/docs/layouts/shortcodes/tabpane.html new file mode 100644 index 000000000..8b0156618 --- /dev/null +++ b/docs/layouts/shortcodes/tabpane.html @@ -0,0 +1,175 @@ +{{/* Check parameter types */ -}} + +{{ $tpPersistAttrName := "data-td-tp-persist" -}} + +{{ with .Get "langEqualsHeader" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "langEqualsHeader" (printf "%T" .) $.Position -}} + {{ end -}} +{{ end -}} + +{{ with .Get "text" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "text" (printf "%T" .) $.Position -}} + {{ end -}} +{{ end -}} + +{{ $_persistLang := .Get "persistLang" -}} +{{ if and (ne $_persistLang nil) (ne $_persistLang "") -}} + {{ if ne ( printf "%T" $_persistLang ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "persistLang" (printf "%T" $_persistLang) $.Position -}} + {{ else -}} + {{ warnf "Shortcode %q parameter `persistLang` is deprecated, use `persist` instead: %s" $.Name $.Position -}} + {{ end -}} +{{ end -}} + +{{ $_persist := .Get "persist" -}} +{{ with $_persist -}} + {{ $matched := findRE "^(header|lang|disabled)$" . -}} + {{ if not $matched -}} + {{ errorf "Shortcode %q: parameter %q should be one of 'header', 'lang', or 'disabled'; but got %s. Error position: %s" $.Name "persist" $_persist $.Position -}} + {{ end -}} +{{ end -}} + +{{ with .Get "right" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "right" (printf "%T" .) $.Position -}} + {{ end -}} +{{ end -}} + +{{/* Set values given defined within tabpane */ -}} +{{ $langPane := default "" ($.Get "lang") -}} +{{ $hloptionsPane := default "" ($.Get "highlight") -}} +{{ $textPane := default false ($.Get "text") -}} +{{ $langEqualsHeader := default false ($.Get "langEqualsHeader") -}} +{{ $deprecatedPersistLang := $_persistLang | default true -}} +{{ $persistKeyKind := $_persist + | default (cond (or $textPane (ne "" $langPane)) "header" "lang") -}} +{{ $persistTabpane := and $deprecatedPersistLang (ne $persistKeyKind "disabled") -}} +{{ $rightPane := default false ($.Get "right") -}} +{{ $activeSet := false -}} +{{/* Scratchpad gets populated through call to .Inner */ -}} +{{ .Inner -}} + +{{ $duplicate := false -}} +{{ $duplicateKey := "" -}} +{{ $persistKeyList := slice -}} +{{ $tabPaneOrdinal := .Ordinal -}} + +{{/* Nav tabs */ -}} + + +{{ if $duplicate -}} + {{ warnf "Shortcode %q: duplicate tab-persistence key %q detected, disabling persistance to avoid multiple tab display. Position: %s" $.Name $duplicateKey $.Position -}} +{{ end -}} + +{{ $activeSet = false -}} + +{{/* Tab panes */ -}} +
    + {{- range $index, $element := $.Scratch.Get "tabs" -}} + + {{ $lang := $langPane -}} + {{ if $langEqualsHeader -}} + {{ $lang = $element.header -}} + {{ end -}} + {{ with $element.language -}} + {{ $lang = . -}} + {{ end -}} + + {{ $enabled := not $element.disabled -}} + + {{ $hloptions := $hloptionsPane -}} + {{ with $element.highlight -}} + {{ $hloptions = . -}} + {{ end -}} + + {{ $text := $textPane -}} + {{ with $element.text -}} + {{ $text = . }} + {{ end -}} + + {{ $tabid := printf "tabs-%02v-%v-tab" $tabPaneOrdinal $index | anchorize -}} + {{ $entryid := printf "tabs-%02v-%v" $tabPaneOrdinal $index | anchorize }} + {{ $isActive := and $enabled (not $activeSet) -}} + +
    + {{ if $text -}} + {{ index . "content" -}} + {{ else -}} + {{ highlight (trim (index . "content") "\r\n") $lang $hloptions -}} + {{ end }} +
    + + {{- end }} +
    diff --git a/docs/layouts/swagger/baseof.html b/docs/layouts/swagger/baseof.html new file mode 100644 index 000000000..9c018bba1 --- /dev/null +++ b/docs/layouts/swagger/baseof.html @@ -0,0 +1,38 @@ + + + + {{ partial "head.html" . }} + {{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }} + + + +
    + {{ partial "navbar.html" . }} +
    +
    +
    +
    + + +
    + {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }} + + + {{ block "main" . }}{{ end }} +
    +
    +
    + {{ partial "footer.html" . }} +
    + {{ partial "scripts.html" . }} + + diff --git a/docs/layouts/swagger/list.html b/docs/layouts/swagger/list.html new file mode 100644 index 000000000..210dd2c42 --- /dev/null +++ b/docs/layouts/swagger/list.html @@ -0,0 +1,20 @@ +{{ define "main" }} +
    +

    {{ .Title }}

    + {{ with .Params.description }}
    {{ . | markdownify }}
    {{ end }} +
    + {{ partial "taxonomy_terms_article_wrapper.html" . -}} + {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} + {{ partial "reading-time.html" . -}} + {{ end -}} +
    + {{ .Content }} + {{ partial "section-index.html" . -}} + {{ partial "feedback.html" . -}} + {{ if (.Site.Config.Services.Disqus.Shortname) -}} +
    + {{ partial "disqus-comment.html" . -}} + {{ end -}} + {{ partial "page-meta-lastmod.html" . -}} +
    +{{ end -}} diff --git a/docs/layouts/swagger/single.html b/docs/layouts/swagger/single.html new file mode 100644 index 000000000..00cb3ab91 --- /dev/null +++ b/docs/layouts/swagger/single.html @@ -0,0 +1,3 @@ +{{ define "main" }} +{{ .Render "content" }} +{{ end }} \ No newline at end of file diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 000000000..44c0e1f37 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,47 @@ +{ + "name": "docsy-example-site", + "version": "0.10.0", + "version.next": "0.10.1-dev.0-unreleased", + "description": "Example site that uses Docsy theme for technical documentation.", + "repository": "github:google/docsy-example", + "homepage": "https://example.docsy.dev", + "author": "Docsy Authors", + "license": "Apache-2.0", + "bugs": "https://github.com/google/docsy-example/issues", + "spelling": "cSpell:ignore docsy hugo htmltest precheck postbuild -", + "scripts": { + "_build": "npm run _hugo-dev --", + "_check:links": "echo IMPLEMENTATION PENDING for check-links; echo", + "_hugo": "hugo --cleanDestinationDir", + "_hugo-dev": "npm run _hugo -- -e dev -DFE", + "_local": "npx cross-env HUGO_MODULE_WORKSPACE=docsy.work", + "_serve": "npm run _hugo-dev -- --minify serve --renderToMemory", + "build:preview": "npm run _hugo-dev -- --minify --baseURL \"${DEPLOY_PRIME_URL:-/}\"", + "build:production": "npm run _hugo -- --minify", + "build": "npm run _build -- ", + "check:links:all": "HTMLTEST_ARGS= npm run _check:links", + "check:links": "npm run _check:links", + "clean": "rm -Rf public/* resources", + "local": "npm run _local -- npm run", + "make:public": "git init -b main public", + "precheck:links:all": "npm run build", + "precheck:links": "npm run build", + "postbuild:preview": "npm run _check:links", + "postbuild:production": "npm run _check:links", + "serve": "npm run _serve", + "test": "npm run check:links", + "update:dep": "npm install --save-dev autoprefixer@latest postcss-cli@latest", + "update:hugo": "npm install --save-dev --save-exact hugo-extended@latest" + }, + "devDependencies": { + "autoprefixer": "^10.4.14", + "cross-env": "^7.0.3", + "hugo-extended": "0.127.0", + "postcss-cli": "^11.0.0" + }, + "private": true, + "prettier": { + "proseWrap": "always", + "singleQuote": true + } +} diff --git a/docs/rus/best-practices.md b/docs/rus/best-practices.md deleted file mode 100644 index 192d8422c..000000000 --- a/docs/rus/best-practices.md +++ /dev/null @@ -1,5 +0,0 @@ -# Практики использования - -- [Discard Overflow](best_practices/discard-overflow.md) -- [RPS на инстанс](best_practices/rps-per-instance.md) -- [Общий транспорт](best_practices/shared-client.md) \ No newline at end of file diff --git a/docs/rus/custom.md b/docs/rus/custom.md deleted file mode 100644 index 770b920a7..000000000 --- a/docs/rus/custom.md +++ /dev/null @@ -1,455 +0,0 @@ -[К содержанию](index.md) - ---- - -# Custom guns - -- [Basic tutorial](#basic-tutorial) -- [gRPC](#grpc) -- [Websockets](#websockets) - -## Basic tutorial - -You can create you own Golang-based gun with _pandora_. - -There is an example of custom gun shooting via gRPC. - -We create a new gun and define `shoot` method for it w/ our test logic. - -You can find examples of custom guns' code below: -- [gRPC](#gRPC) -- [Websockets](#Websockets) - -Now it's time to compile our gun. Install deps and compile your custom gun file (`go build my_custom_gun.go`). - -After that step you'll get `my_custom_gun` binary file, it is compiled pandora with your custom gun inside. - -Now its time to create `load.yaml`: - -```yaml -pools: - - id: HTTP pool - gun: - type: my_custom_gun_name # custom gun name (specified at `register.Gun("my_custom_gun_name", ...`) - target: "your_grpc_host:your_grpc_port" - ammo: - type: custom_provider - source: - type: file - path: ./json.ammo - result: - type: phout - destination: ./phout.log - rps: { duration: 30s, type: line, from: 1, to: 2 } - startup: - type: once - times: 10 - log: -``` - -And create ammofile `./json.ammo`: - -```yaml -{"tag": "/MyCase1", "Param1": "146837693,146837692,146837691"} -{"tag": "/MyCase2", "Param2": "555", "Param1": "500002"} -``` - - -We are ready to shoot. Try it. - - -## gRPC - -```go -// create a package -package main - -// import some pandora stuff -// and stuff you need for your scenario -// and protobuf contracts for your grpc service - -import ( - "log" - "context" - "strconv" - "strings" - "time" - - "github.com/golang/protobuf/ptypes/timestamp" - "github.com/satori/go.uuid" - "github.com/spf13/afero" - "google.golang.org/grpc" - pb "my_package/my_protobuf_contracts" - - "github.com/yandex/pandora/cli" - "github.com/yandex/pandora/components/phttp/import" - "github.com/yandex/pandora/core" - "github.com/yandex/pandora/core/aggregator/netsample" - "github.com/yandex/pandora/core/import" - "github.com/yandex/pandora/core/register" -) - -type Ammo struct { - Tag string - Param1 string - Param2 string - Param3 string -} - -type Sample struct { - URL string - ShootTimeSeconds float64 -} - -type GunConfig struct { - Target string `validate:"required"` // Configuration will fail, without target defined -} - -type Gun struct { - // Configured on construction. - client grpc.ClientConn - conf GunConfig - // Configured on Bind, before shooting - aggr core.Aggregator // May be your custom Aggregator. - core.GunDeps -} - -func NewGun(conf GunConfig) *Gun { - return &Gun{conf: conf} -} - -func (g *Gun) Bind(aggr core.Aggregator, deps core.GunDeps) error { - // create gRPC stub at gun initialization - conn, err := grpc.Dial( - g.conf.Target, - grpc.WithInsecure(), - grpc.WithTimeout(time.Second), - grpc.WithUserAgent("load test, pandora custom shooter")) - if err != nil { - log.Fatalf("FATAL: %s", err) - } - g.client = *conn - g.aggr = aggr - g.GunDeps = deps - return nil -} - -func (g *Gun) Shoot(ammo core.Ammo) { - customAmmo := ammo.(*Ammo) - g.shoot(customAmmo) -} - - -func (g *Gun) case1_method(client pb.MyClient, ammo *Ammo) int { - code := 0 - // prepare list of ids from ammo - var itemIDs []int64 - for _, id := range strings.Split(ammo.Param1, ",") { - if id == "" { - continue - } - itemID, err := strconv.ParseInt(id, 10, 64) - if err != nil { - log.Printf("Ammo parse FATAL: %s", err) - code = 314 - } - itemIDs = append(itemIDs, itemID) - } - - out, err := client.GetSomeData( - context.TODO(), &pb.ItemsRequest{ - itemIDs}) - - if err != nil { - log.Printf("FATAL: %s", err) - code = 500 - } - - if out != nil { - code = 200 - } - return code -} - -func (g *Gun) case2_method(client pb.MyClient, ammo *Ammo) int { - code := 0 - // prepare item_id and warehouse_id - item_id, err := strconv.ParseInt(ammo.Param1, 10, 0) - if err != nil { - log.Printf("Failed to parse ammo FATAL", err) - code = 314 - } - warehouse_id, err2 := strconv.ParseInt(ammo.Param2, 10, 0) - if err2 != nil { - log.Printf("Failed to parse ammo FATAL", err2) - code = 314 - } - - items := []*pb.SomeItem{} - items = append(items, &pb.SomeItem{ - item_id, - warehouse_id, - 1, - ×tamp.Timestamp{time.Now().Unix(), 111} - }) - - out2, err3 := client.GetSomeDataSecond( - context.TODO(), &pb.SomeRequest{ - uuid.Must(uuid.NewV4()).String(), - 1, - items}) - if err3 != nil { - log.Printf("FATAL", err3) - code = 316 - } - - if out2 != nil { - code = 200 - } - - - return code -} - -func (g *Gun) shoot(ammo *Ammo) { - code := 0 - sample := netsample.Acquire(ammo.Tag) - - conn := g.client - client := pb.NewClient(&conn) - - switch ammo.Tag { - case "/MyCase1": - code = g.case1_method(client, ammo) - case "/MyCase2": - code = g.case2_method(client, ammo) - default: - code = 404 - } - - defer func() { - sample.SetProtoCode(code) - g.aggr.Report(sample) - }() -} - -func main() { - //debug.SetGCPercent(-1) - // Standard imports. - fs := afero.NewOsFs() - coreimport.Import(fs) - // May not be imported, if you don't need http guns and etc. - phttp.Import(fs) - - // Custom imports. Integrate your custom types into configuration system. - coreimport.RegisterCustomJSONProvider("custom_provider", func() core.Ammo { return &Ammo{} }) - - register.Gun("my_custom_gun_name", NewGun, func() GunConfig { - return GunConfig{ - Target: "default target", - } - }) - - cli.Run() -} -``` - -## Websockets - -```go -// create a package -package main - -// import some pandora stuff -// and stuff you need for your scenario -// and protobuf contracts for your grpc service - -import ( - "log" - "context" - "strconv" - "strings" - "time" - - "github.com/golang/protobuf/ptypes/timestamp" - "github.com/satori/go.uuid" - "github.com/spf13/afero" - "google.golang.org/grpc" - pb "my_package/my_protobuf_contracts" - - "github.com/yandex/pandora/cli" - "github.com/yandex/pandora/components/phttp/import" - "github.com/yandex/pandora/core" - "github.com/yandex/pandora/core/aggregator/netsample" - "github.com/yandex/pandora/core/import" - "github.com/yandex/pandora/core/register" -) - -type Ammo struct { - Tag string - Param1 string - Param2 string - Param3 string -} - -type Sample struct { - URL string - ShootTimeSeconds float64 -} - -type GunConfig struct { - Target string `validate:"required"` // Configuration will fail, without target defined -} - -type Gun struct { - // Configured on construction. - client grpc.ClientConn - conf GunConfig - // Configured on Bind, before shooting - aggr core.Aggregator // May be your custom Aggregator. - core.GunDeps -} - -func NewGun(conf GunConfig) *Gun { - return &Gun{conf: conf} -} - -func (g *Gun) Bind(aggr core.Aggregator, deps core.GunDeps) error { - // create gRPC stub at gun initialization - conn, err := grpc.Dial( - g.conf.Target, - grpc.WithInsecure(), - grpc.WithTimeout(time.Second), - grpc.WithUserAgent("load test, pandora custom shooter")) - if err != nil { - log.Fatalf("FATAL: %s", err) - } - g.client = *conn - g.aggr = aggr - g.GunDeps = deps - return nil -} - -func (g *Gun) Shoot(ammo core.Ammo) { - customAmmo := ammo.(*Ammo) - g.shoot(customAmmo) -} - - -func (g *Gun) case1_method(client pb.MyClient, ammo *Ammo) int { - code := 0 - // prepare list of ids from ammo - var itemIDs []int64 - for _, id := range strings.Split(ammo.Param1, ",") { - if id == "" { - continue - } - itemID, err := strconv.ParseInt(id, 10, 64) - if err != nil { - log.Printf("Ammo parse FATAL: %s", err) - code = 314 - } - itemIDs = append(itemIDs, itemID) - } - - out, err := client.GetSomeData( - context.TODO(), &pb.ItemsRequest{ - itemIDs}) - - if err != nil { - log.Printf("FATAL: %s", err) - code = 500 - } - - if out != nil { - code = 200 - } - return code -} - -func (g *Gun) case2_method(client pb.MyClient, ammo *Ammo) int { - code := 0 - // prepare item_id and warehouse_id - item_id, err := strconv.ParseInt(ammo.Param1, 10, 0) - if err != nil { - log.Printf("Failed to parse ammo FATAL", err) - code = 314 - } - warehouse_id, err2 := strconv.ParseInt(ammo.Param2, 10, 0) - if err2 != nil { - log.Printf("Failed to parse ammo FATAL", err2) - code = 314 - } - - items := []*pb.SomeItem{} - items = append(items, &pb.SomeItem{ - item_id, - warehouse_id, - 1, - ×tamp.Timestamp{time.Now().Unix(), 111} - }) - - out2, err3 := client.GetSomeDataSecond( - context.TODO(), &pb.SomeRequest{ - uuid.Must(uuid.NewV4()).String(), - 1, - items}) - if err3 != nil { - log.Printf("FATAL", err3) - code = 316 - } - - if out2 != nil { - code = 200 - } - - - return code -} - -func (g *Gun) shoot(ammo *Ammo) { - code := 0 - sample := netsample.Acquire(ammo.Tag) - - conn := g.client - client := pb.NewClient(&conn) - - switch ammo.Tag { - case "/MyCase1": - code = g.case1_method(client, ammo) - case "/MyCase2": - code = g.case2_method(client, ammo) - default: - code = 404 - } - - defer func() { - sample.SetProtoCode(code) - g.aggr.Report(sample) - }() -} - -func main() { - //debug.SetGCPercent(-1) - // Standard imports. - fs := afero.NewOsFs() - coreimport.Import(fs) - // May not be imported, if you don't need http guns and etc. - phttp.Import(fs) - - // Custom imports. Integrate your custom types into configuration system. - coreimport.RegisterCustomJSONProvider("custom_provider", func() core.Ammo { return &Ammo{} }) - - register.Gun("my_custom_gun_name", NewGun, func() GunConfig { - return GunConfig{ - Target: "default target", - } - }) - - cli.Run() -} -``` - ---- - -[К содержанию](index.md) \ No newline at end of file diff --git a/docs/rus/index.md b/docs/rus/index.md deleted file mode 100644 index e81c931df..000000000 --- a/docs/rus/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# Добро пожаловать в документацию Pandora! - -Pandora - это высокопроизводительный генератор нагрузки на языке Go. Он имеет встроенную поддержку HTTP(S) и HTTP/2, и вы можете писать собственные сценарии нагрузки на языке Go, компилируя их непосредственно перед тестированием. - -## Содержание - -- [Установка](install.md) -- [Конфигурация](config.md) -- [Первый тест](tutorial.md) -- [Профиль нагрузки](load-profile.md) -- [Профиль создание инстансов](startup.md) -- [HTTP providers](providers.md) -- [HTTP генератор](http-generator.md) -- [gRPC генератор](grpc-generator.md) -- [Сценарный генератор / HTTP](scenario-http-generator.md) -- [Сценарный генератор / gRPC](scenario-grpc-generator.md) -- [Custom](custom.md) -- [Практики использования](best-practices.md) - - [Discard Overflow](best_practices/discard-overflow.md) - - [RPS на инстанс](best_practices/rps-per-instance.md) - - [Общий транспорт](best_practices/shared-client.md) -- [Производительность Pandora](performance.md) -- [Архитектура](architecture.md) - ---- - -[English](../index.md) diff --git a/docs/images/architecture.graphml b/docs/static/images/architecture.graphml similarity index 100% rename from docs/images/architecture.graphml rename to docs/static/images/architecture.graphml diff --git a/docs/images/architecture.png b/docs/static/images/architecture.png similarity index 100% rename from docs/images/architecture.png rename to docs/static/images/architecture.png diff --git a/docs/images/http_100kb_net.png b/docs/static/images/http_100kb_net.png similarity index 100% rename from docs/images/http_100kb_net.png rename to docs/static/images/http_100kb_net.png diff --git a/docs/images/http_connection_close_td.png b/docs/static/images/http_connection_close_td.png similarity index 100% rename from docs/images/http_connection_close_td.png rename to docs/static/images/http_connection_close_td.png diff --git a/docs/images/http_delay_10s_instances.png b/docs/static/images/http_delay_10s_instances.png similarity index 100% rename from docs/images/http_delay_10s_instances.png rename to docs/static/images/http_delay_10s_instances.png diff --git a/docs/images/http_delay_10s_td.png b/docs/static/images/http_delay_10s_td.png similarity index 100% rename from docs/images/http_delay_10s_td.png rename to docs/static/images/http_delay_10s_td.png diff --git a/docs/images/http_keep_alive_td.png b/docs/static/images/http_keep_alive_td.png similarity index 100% rename from docs/images/http_keep_alive_td.png rename to docs/static/images/http_keep_alive_td.png diff --git a/docs/images/http_srv_fail_q.png b/docs/static/images/http_srv_fail_q.png similarity index 100% rename from docs/images/http_srv_fail_q.png rename to docs/static/images/http_srv_fail_q.png diff --git a/docs/images/scn_cases.png b/docs/static/images/scn_cases.png similarity index 100% rename from docs/images/scn_cases.png rename to docs/static/images/scn_cases.png