From 565311f245779fde0a0238561b857b719ac929b4 Mon Sep 17 00:00:00 2001 From: Eric Schneider <37347760+eric-schneider@users.noreply.github.com> Date: Mon, 26 Feb 2024 10:00:33 -0800 Subject: [PATCH] =?UTF-8?q?DOC-4217:=20Add=20=E2=80=9Cpage=20source?= =?UTF-8?q?=E2=80=9D=20links=20to=20preview-src=20pages=20(#101)=20[no-rel?= =?UTF-8?q?ease]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add “page source” links to preview-src pages * Update README with latest automation enhancements --- README.adoc | 88 +++++++------------ preview-src/asciidoc/admonitions.adoc | 2 + preview-src/asciidoc/blocks.adoc | 2 + preview-src/asciidoc/code.adoc | 12 ++- preview-src/asciidoc/images.adoc | 2 + preview-src/asciidoc/lists.adoc | 2 + preview-src/asciidoc/tables.adoc | 2 + preview-src/asciidoc/tabsets.adoc | 2 + preview-src/asciidoc/text-formatting.adoc | 2 + preview-src/page-templates/full.adoc | 2 + .../page-templates/integrations-detail.adoc | 2 + .../page-templates/integrations-overview.adoc | 2 + preview-src/page-templates/landing.adoc | 28 +++--- preview-src/page-templates/tutorial.adoc | 2 + 14 files changed, 77 insertions(+), 73 deletions(-) diff --git a/README.adoc b/README.adoc index 785f09f3..17b2bea5 100644 --- a/README.adoc +++ b/README.adoc @@ -18,7 +18,8 @@ ifdef::env-github[] endif::[] // Project URLs: :url-project: https://github.com/riptano/docs-ui -:url-preview: https://riptano.github.io/docs-ui/main +:url-ui-preview: https://riptano.github.io/docs-ui/main +:url-ui-bundle-latest: {url-project}/releases/latest // :url-ci-pipelines: {url-project}/pipelines // :img-ci-status: {url-project}/badges/master/pipeline.svg :url-docs-home: https://github.com/riptano/docs-home @@ -43,10 +44,10 @@ endif::[] :url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map :url-create-release: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release -// image:{img-ci-status}[CI Status (GitLab CI), link={url-ci-pipelines}] -// ifdef::badges[] -// image:https://img.shields.io/static/v1?label=release&message={current-release}&color=blue[Latest Release,link={url-project}/releases/download/{current-release}/ui-bundle.zip,format=svg] -// endif::[] +ifdef::badges[] +image:https://img.shields.io/github/v/release/riptano/docs-ui?label=latest%20release&labelColor=%23232324&color=%237724aa["Latest UI bundle release (GitHub)", link={url-ui-bundle-latest}] +image:https://img.shields.io/badge/Preview-%237724aa["Latest UI preview (GitHub Pages)", link={url-ui-preview}] +endif::[] This project is used to develop and distribute the UI template for {url-datastax-docs}. It is a fork of the {url-antora-default-ui}[Antora Default UI] that has been customized for our needs. @@ -55,8 +56,9 @@ The repository itself produces a UI bundle that can be applied when generating a The UI bundle contains the HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and (site-wide) images. As such, it provides both the visual theme and user interactions for the documentation site. -You can see a preview of the DataStax Docs UI at {url-preview}. +* Latest UI preview: {url-ui-preview} +* Latest UI bundle release: {url-ui-bundle-latest} toc::[] @@ -243,6 +245,11 @@ This works by monitoring the project for changes, running the `preview:build` ta Press kbd:[Ctrl+C] to stop the preview server and end the continuous build. +[NOTE] +==== +Opening or updating a pull request against the `main` branch triggers an automatic `gulp preview` deployment to GitHub Pages so that reviewers can view your latest changes without having to run the preview locally. +==== + [#create-bundle] === Package for use with Antora @@ -267,6 +274,12 @@ gulp bundle:pack The UI bundle will again be available at [.path]_build/ui-bundle.zip_. +[NOTE] +==== +UI bundles for the DataStax documentation site are automatically published via automation. +See <>. +==== + ==== Source maps The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle. @@ -288,67 +301,28 @@ In this case, the bundle will include the source maps, which can be used for deb ==== Using TailwindCSS -This project uses TailwindCSS. To learn more see xref:{url-tailwind-readme}[TailwindCSS README]. +This project uses TailwindCSS. +To learn more see xref:{url-tailwind-readme}[TailwindCSS README]. -== Release the UI bundle +[#automatic-ui-release] +== Automatic UI bundle release Once you're satisfied with the changes you've made to the UI, you'll need to open a pull request to merge your changes into the `main` branch. -After your changes have been reviewed and merged, you can then choose to make those changes available in the production UI by publishing a new release to this repository and attaching the latest `ui-bundle.zip` file. +Upon merging a pull request into `main`, the following automation occurs: -=== Bundle release procedure +. A new UI bundle is built using `gulp bundle` (linting also occurs during this step). -. Start by making sure you've completed the <>. +. Assuming a successful build, a new tag is applied to the latest commit (incremented from the previous `prod-#` tag). -. Create the release commit. -+ -Edit https://github.com/riptano/docs-ui/blob/bdf6484e46f41cff17238a7ef5aeae5368622d2c/README.adoc?plain=1#L3[README.adoc] directly in GitHub and increment the `:current-release:` attribute to the next version number. -+ -[source,asciidoc] ----- -:current-release: prod-* <.> ----- -<.> Add +1 to the version number -+ -This should be the only change in the commit, and the commit message should take the form of *Release prod-*. -If you have Admin privileges to the repository, you can commit the changes directly to `main`. -Otherwise, you'll need to open a PR. +. A new `prod-#` {url-project}/releases[release] is published with auto-generated release notes and the UI bundle release asset. -. Once the release commit is merged, open your local copy of the repository in a terminal and retrieve the latest changes from `main`. -+ -[source,shell] ----- -git switch main && git pull ----- - -. Pack the UI bundle as described in <>. -+ -[source,shell] ----- -gulp bundle ----- - -. Create a new release (see {url-create-release}[GitHub documentation]). -.. Create a new tag named after the new version (e.g., `prod-2`). -The tag needs to target the `main` branch. -.. Make sure the *Title* of the release is the same name as the tag. -(The release title and the tag name should always be made the same, as it makes releases easier to identify.) -.. Instead of manually adding a description for the release, just click *Generate release notes*. -This automatically adds a description that highlights the functional changes that have been added since the last release. -.. Attach the UI bundle (`ui-bundle.zip`) as a release asset. -.. (Optional) Check the box labeled *This is a pre-release* if you don't want the release to be generally available. -+ -Selecting this option is helpful if you want to publish a new UI bundle for testing purposes. -You can edit the release later to remove the *Pre-release* label if desired. -.. When you're ready, publish the release. - -Once the new release is published, the attached bundle can then be downloaded from the repository using a unique URL found on the {url-project}/releases[releases page]. - -[IMPORTANT] +[TIP] ==== -All production builds of the DataStax docs are configured to pull the latest, _non-pre-release_ UI bundle. -Once you've publish a new release, all subsequent site builds that use the configuration described in <> will consume the new UI bundle. +If you don't want your pull request to trigger an automatic release, e.g. you're only making updates to the README or `preview-src` files, you can skip the automation by including `[no-release]` in the commit message. ==== +Once the release is published, you can apply it by updating your Antora playbook to point to the new UI bundle URL. +To apply it to the DataStax documentation site, you'll need to update the playbook in the {url-datastax-docs-repo}[datastax-docs-site] repository. == Copyright and license diff --git a/preview-src/asciidoc/admonitions.adoc b/preview-src/asciidoc/admonitions.adoc index 5cd8d05c..bbffd37b 100644 --- a/preview-src/asciidoc/admonitions.adoc +++ b/preview-src/asciidoc/admonitions.adoc @@ -3,6 +3,8 @@ :idseparator: - :table-caption!: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/admonitions.adoc + == Basic admonitions .Optional title diff --git a/preview-src/asciidoc/blocks.adoc b/preview-src/asciidoc/blocks.adoc index 60a8391b..bee87148 100644 --- a/preview-src/asciidoc/blocks.adoc +++ b/preview-src/asciidoc/blocks.adoc @@ -4,6 +4,8 @@ :example-caption!: :stem: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/blocks.adoc + == Collapsible blocks .Basic collapsible block diff --git a/preview-src/asciidoc/code.adoc b/preview-src/asciidoc/code.adoc index 7f56a6a9..93e862a4 100644 --- a/preview-src/asciidoc/code.adoc +++ b/preview-src/asciidoc/code.adoc @@ -2,6 +2,8 @@ :idprefix: :idseparator: - +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/code.adoc + == Inline code Monospace text formatting is typically used to represent text shown in `computer terminals` or `code editors` (often referred to as a codespan). @@ -93,13 +95,17 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. ---- -=== Text formatting +=== Text formatting (variables) -[source,bash,subs="quotes"] +[source,sql,subs="verbatim,quotes"] ---- -cd /Users/*_your-name_*/repos/astra-vector-docs/build/site +DESCRIBE **KEYSPACE_NAME**.**TABLE_NAME** ---- +Replace the following: + +* *`KEYSPACE_NAME`*: The name of the keyspace that contains the table you want to migrate. +* *`TABLE_NAME`*: The name of the table that contains the data you want to migrate. == Callouts diff --git a/preview-src/asciidoc/images.adoc b/preview-src/asciidoc/images.adoc index 2dae51a1..293b38c4 100644 --- a/preview-src/asciidoc/images.adoc +++ b/preview-src/asciidoc/images.adoc @@ -3,6 +3,8 @@ :idseparator: - :figure-caption!: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/images.adoc + == Block images .Optional title diff --git a/preview-src/asciidoc/lists.adoc b/preview-src/asciidoc/lists.adoc index f0771f1f..ed50eef7 100644 --- a/preview-src/asciidoc/lists.adoc +++ b/preview-src/asciidoc/lists.adoc @@ -3,6 +3,8 @@ :idseparator: - :table-caption!: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/lists.adoc + == Unordered list * List item diff --git a/preview-src/asciidoc/tables.adoc b/preview-src/asciidoc/tables.adoc index 31ee0947..6295e642 100644 --- a/preview-src/asciidoc/tables.adoc +++ b/preview-src/asciidoc/tables.adoc @@ -3,6 +3,8 @@ :idseparator: - :table-caption!: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/tables.adoc + == Basic table .Optional title diff --git a/preview-src/asciidoc/tabsets.adoc b/preview-src/asciidoc/tabsets.adoc index 453a7de6..5b970f46 100644 --- a/preview-src/asciidoc/tabsets.adoc +++ b/preview-src/asciidoc/tabsets.adoc @@ -9,6 +9,8 @@ :python-icon: image:../img/python-original.svg[,22] :shell-icon: image:../img/shell-original.svg[,20] +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/tabsets.adoc + [NOTE] ==== Tabsets depend on the https://github.com/asciidoctor/asciidoctor-tabs[Asciidoctor Tabs] extension. diff --git a/preview-src/asciidoc/text-formatting.adoc b/preview-src/asciidoc/text-formatting.adoc index df6746e1..6be630ae 100644 --- a/preview-src/asciidoc/text-formatting.adoc +++ b/preview-src/asciidoc/text-formatting.adoc @@ -3,6 +3,8 @@ :idseparator: - :experimental: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/text-formatting.adoc + A paragraph can be defined as one or more lines of consecutive text that are logically grouped together. To differentiate between paragraphs, you simply need to insert at least one blank line between them. diff --git a/preview-src/page-templates/full.adoc b/preview-src/page-templates/full.adoc index dacbe5a4..111fb373 100644 --- a/preview-src/page-templates/full.adoc +++ b/preview-src/page-templates/full.adoc @@ -1,6 +1,8 @@ = {company} Astra :page-layout: full +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/page-templates/full.adoc + [.max-w-[650px]] DataStax Astra is a cutting-edge cloud-native database platform designed to empower developers. Harnessing the strengths of vector databases, serverless computing, and real-time streaming, Astra propels application development into the next generation. diff --git a/preview-src/page-templates/integrations-detail.adoc b/preview-src/page-templates/integrations-detail.adoc index 8fb3f481..c241e581 100644 --- a/preview-src/page-templates/integrations-detail.adoc +++ b/preview-src/page-templates/integrations-detail.adoc @@ -9,6 +9,8 @@ :page-tags: Machine Learning Frameworks, Embedding Services, Astra, SDK :figure-caption!: +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/page-templates/integrations-detail.adoc + ._Integration-specific formatting_ [%collapsible%open] ==== diff --git a/preview-src/page-templates/integrations-overview.adoc b/preview-src/page-templates/integrations-overview.adoc index 920c8115..5514a4e6 100644 --- a/preview-src/page-templates/integrations-overview.adoc +++ b/preview-src/page-templates/integrations-overview.adoc @@ -9,6 +9,8 @@ :llamaindex-icon: image:../img/llamaindex.svg[,20] :cassio-icon: image:../img/cassio.svg[,20] +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/page-templates/integrations-overview.adoc + Dive into our curated marketplace of integrations that elevate the capabilities of Astra's vector databases. Whether you're looking to amplify your machine learning workflows, diff --git a/preview-src/page-templates/landing.adoc b/preview-src/page-templates/landing.adoc index 2693e477..1c151f74 100644 --- a/preview-src/page-templates/landing.adoc +++ b/preview-src/page-templates/landing.adoc @@ -2,6 +2,8 @@ :page-layout: landing :product: Astra DB +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/page-templates/landing.adoc + {product} empowers developers to build cutting-edge AI applications with robust APIs, real-time data handling, and seamless ecosystem integrations. Read our xref:get-started:concepts.adoc[introduction to vector databases] if you're new to {product}. [.[&>h2]:!hidden] @@ -11,11 +13,11 @@ ++++
- +

Get started

- +

Ready to work with {product}? Dive into the quickstart guide and learn how to create a database, connect, and load data in a matter of minutes.

- +
xref:get-started:quickstart.adoc[Quickstart,role="btn btn-primary btn-solid"] https://astra.datastax.com[Create Astra Account^,role="btn btn-neutral btn-outlined external"] @@ -49,7 +51,7 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
- +

Create database

@@ -62,7 +64,7 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
- +

Load data

@@ -75,7 +77,7 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
- +

Explore your data

@@ -85,16 +87,16 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
xref:createdatabase.adoc[Explore your data]
- +

Expand your {product} knowledge

- +
- +

Integrations

@@ -116,7 +118,7 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
- +
auto_stories

Tutorials

@@ -130,11 +132,11 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
xref:createdatabase.adoc[Build a recommendation system with vector search]
- +
- +
handyman

API references

@@ -148,7 +150,7 @@ c.vector_find([0.15, 0.1, 0.1, 0.35, 0.55])
xref:createdatabase.adoc[APIs for non-vector databases]
- +
++++ diff --git a/preview-src/page-templates/tutorial.adoc b/preview-src/page-templates/tutorial.adoc index 1539b202..1e9d82df 100644 --- a/preview-src/page-templates/tutorial.adoc +++ b/preview-src/page-templates/tutorial.adoc @@ -8,6 +8,8 @@ :astra-json-link: https://docs.datastax.com/en/astra-serverless/docs/develop/dev-with-json.html :keywords: Machine Learning Frameworks, Embeding Services, Astra, SDK +*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/page-templates/tutorial.adoc + .Tutorial-specific formatting [%collapsible%open] ====