Quickstarts for learning the Teradata Vantage database. The documents use the AsciiDoc format. The website is built with Antora.
Contributions are welcome :). See below how to build the documentation website locally.
-
The documentation uses Asciidoc syntax. If you are not familiar with Asciidoc, please check this Asciidoc tutorial: https://asciidoctor.org/docs/asciidoc-writers-guide/.
-
We use this GitHub repository to track content. The
main
branch reflects the what's on the website. Each time a commit is made tomain
branch, a deployment is triggered that pushes the changes to GitHub Pages. It takes about 2 minutes for a commit to be deployed. -
Simple changes to content can be done through a pull request directly from GitHub's website. For large changes, e.g. more sophisticated reformatting or adding a new page, we recommend that you fork the repo, clone locally and follow instructions how to build the website locally.
-
Each page corresponds to an asciidoc file in the repository. Pages are located in
modules/ROOT/pages
directory. Page files must have.adoc
suffix. -
We use Antora to build the documentation website. This guide explains how to run Antora locally to test changes before submitting a pull request. To learn more about Antora see https://docs.antora.org/antora/3.0/.
- Go to the Quickstarts website and navigate to the page you want to edit.
- Click on
Edit this page
link in the top-right corner. You will be taken to the corresponding file on GitHub. - Click on
Edit this file
icon, enter your modifications and submit as a pull request.
- Fork the repository and clone it locally.
- Add a new file to
modules/ROOT/pages
directory. Give the file a meaningful but short name. The file needs to have.adoc
extension. Use only lower-case letters. No spaces are allowed. If you want to use multiple words, use.
as a separator, e.g.getting.started.vmware.adoc
. - Add content to the file.
- Add your new page to the left-hand side navigation by editing
modules/ROOT/nav.adoc
file. The file is a list of links. Make sure you think about where in the menu your target audience will be looking for your document. - Submit your changes as a pull request.
ℹ️ Sometimes pages include content from other files. It's done using
include::
directive, e.g.include::partial$next.steps.adoc[]
. You will find these partials inmodules/ROOT/partials
directory.
Images are located in modules/ROOT/images
directory.
- Add your image to the directory.
- Use
image::
directive to insert an image on a page, e.g.image::gettingstarteddemo.ipynb.png[GettingStartedDemo.ipynb screenshot, width=100%]
. Usewidth=100%
for large images. Usewidth=500
for smaller images. Always give an image an alternate name (GettingStartedDemo.ipynb screenshot
in the example) to increase accessibility of the document.
Attachments are located in modules/ROOT/attachments
directory.
- Add your attachment to the directory.
- Use the regular
link:
directive to insert a link to the attachment. Use{attachmentsdir}
to point to the attachments directory, e.g.link:{attachmentsdir}/example.yaml[Download the YAML example]
.
The website follows the regular Antora supplemental UI solution for customizing the looks and feel. Directory supplemental_ui
contains files that override the original Antora UI files. See Antora's UI documentation for details: https://docs.antora.org/antora-ui-default/.
Sometimes, you want to include the same content on multiple pages. Antora supports it using partials. Partials are Asciidoc snippets that reside in their own files in modules/ROOT/pages/partials
directory. Any valid Asciidoc document is a valid partial.
- Add an
.adoc
file to thepartials
directory. - Include the partial using
include::
directive, e.g.include::partial$running.sample.queries.adoc[]
.
TODO: add content
There are two ways to build documentation locally:
- Build using Docker - this method is quick to setup but the build process takes longer. It's best for occasional contributors.
- Build directly on your machine - this method takes longer to setup but builds are much faster. Use it if you intend to contribute on an ongoing basis.
- Clone the repo:
git clone [email protected]:Teradata/quickstarts.git
- Change dir to quickstarts:
cd quickstarts
- Run build by mapping the document directory to the container:
./build-docker
- The resulting website files will be saved in
./build/site
directory. Open the directory in your browser to view your local copy of the website.
ℹ️ These instructions are for MacOS. Adjust the instructions for your operating system.
- Install Node.js:
brew install nodejs
- Clone the repo:
git clone [email protected]:Teradata/quickstarts.git
- Change dir to quickstarts:
cd quickstarts
- Install dependencies:
npm i
- Build the website:
./buildw
- The resulting website files will be saved in
./build/site
directory. Open the directory in your browser to view your local copy of the website.