Skip to content

Commit

Permalink
Antora site example
Browse files Browse the repository at this point in the history
  • Loading branch information
@humitos
humitos committed Jan 29, 2024
1 parent 8824588 commit 5118fdf
Show file tree
Hide file tree
Showing 6 changed files with 22 additions and 66 deletions.
17 changes: 8 additions & 9 deletions .readthedocs.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,11 @@ build:
os: ubuntu-22.04
tools:
python: "3"
apt_packages:
- tree

sphinx:
configuration: docs/conf.py

python:
install:
- requirements: requirements.txt
nodejs: "16"

This comment has been minimized.

Sign in to view

Copy link
@mojavelinux

mojavelinux Feb 1, 2024

It would be better to use Node.js 18 or Node.js 20 at this point. Node.js 16 is now EOL.

This comment has been minimized.

Sign in to view

Copy link
@man-chi

man-chi Feb 2, 2024

nice, I will update to nodejs 20 in my tutorial-template-antora

This comment has been minimized.

Sign in to view

Copy link
@humitos

humitos Feb 2, 2024

Author Member

Excellent, thanks! Done in 44d0a73
commands:
# Commands from https://docs.antora.org/antora/latest/install-and-run-quickstart/
- npm i -g -D -E @antora/cli@3.1 @antora/site-generator@3.1

This comment has been minimized.

Sign in to view

Copy link
@mojavelinux

mojavelinux Feb 1, 2024

I'd prefer to see the installation of a single package, antora. The package antora is a meta package that automatically installs @antora/cli and @antora/site-generator. I also don't think specifying the version is necessary.

Another option is to use npx to run the antora command, which will automatically install the necessary antora packages.

npx -y antora -v
npx -y antora --fetch antora-playbook.yml

It's also possible to skip the move step by using:

npx -y antora --fetch --to-dir $READTHEDOCS_OUTPUT/html antora-playbook.yml

This comment has been minimized.

Sign in to view

Copy link
@man-chi

man-chi Feb 2, 2024

@mojavelinux
if using the single line command: npx -y antora --fetch --to-dir $READTHEDOCS_OUTPUT/html antora-playbook.yml

how to can I install extension such as: asciidoctor-kroki @antora/lunr-extension asciidoctor-highlight.js ? kindly advise

This comment has been minimized.

Sign in to view

Copy link
@mojavelinux

mojavelinux Feb 2, 2024 •
edited
Loading 

npx -y --package antora --package @antora/lunr-extension antora --fetch --to-dir $READTHEDOCS_OUTPUT/html antora-playbook.yml

See https://docs.npmjs.com/cli/v10/commands/npx

Once you get past installing one extra package, it makes more sense to install the packages first. However, don't install them globally. Installing packages globally is a bad practice as it can lead to unpredictable behavior (because it largely depends on system configuration). It's better to keep all installations within the project.

This comment has been minimized.

Sign in to view

Copy link
@mojavelinux

mojavelinux Feb 2, 2024

Regardless of which installation method you choose to use, I still recommend the use of --to-dir to avoid the extra step of having to move the published files.

This comment has been minimized.

Sign in to view

Copy link
@humitos

humitos Feb 2, 2024

Author Member

Excellent, thanks! I've used the --to-dir in 44d0a73

This comment has been minimized.

Sign in to view

Copy link
@man-chi

man-chi Feb 4, 2024 •
edited
Loading

@mojavelinux
I have tried your single line command
npx -y --package antora --package @antora/lunr-extension antora --fetch --to-dir $READTHEDOCS_OUTPUT/html antora-playbook.yml

but it generated error mesage:

{"level":"fatal","time":1707021230801,"name":"antora","hint":"Add the --stacktrace option to see the cause of the error.","msg":"Cannot find module 'asciidoctor-kroki' at path /home/docs/checkouts/readthedocs.org/user_builds/tutorial-template-antora/checkouts/latest or /home/docs/.npm/_npx/929fe63429c649ca/node_modules/@antora/asciidoc-loader/lib/config\nRequire stack:\n- /home/docs/.npm/_npx/929fe63429c649ca/node_modules/@antora/user-require-helper/lib/index.js\n- /home/docs/.npm/_npx/929fe63429c649ca/node_modules/@antora/cli/lib/cli.js\n- /home/docs/.npm/_npx/929fe63429c649ca/node_modules/@antora/cli/lib/index.js\n- /home/docs/.npm/_npx/929fe63429c649ca/node_modules/@antora/cli/bin/antora"}

may I know how to combine the following two lines into one in .readthedoc.yml

`version: 2

build:
os: ubuntu-22.04
tools:
python: "3"
nodejs: "20"
commands:
# Commands from https://docs.antora.org/antora/latest/install-and-run-quickstart/
- npm install -g asciidoctor asciidoctor-kroki asciidoctor-highlight.js @antora/cli @antora/site-generator @antora/lunr-extension
- npx -y antora --fetch --to-dir $READTHEDOCS_OUTPUT/html antora-playbook.yml`

This comment has been minimized.

Sign in to view

Copy link
@mojavelinux

mojavelinux Feb 4, 2024

If you use npx without first using npm i first, then you need to include a --package option for every package you intend to use. In this case, you are missing --package asciidoctor-kroki.

This comment has been minimized.

Sign in to view

Copy link
@man-chi

man-chi Feb 4, 2024

thanks for your great advice
- antora -v
- antora --fetch antora-playbook.yml
- mkdir $READTHEDOCS_OUTPUT
- mv build/site $READTHEDOCS_OUTPUT/html
14 changes: 14 additions & 0 deletions antora-playbook.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
site:
title: Antora Docs

This comment has been minimized.

Sign in to view

Copy link
@mojavelinux

mojavelinux Feb 1, 2024

I'd prefer if this title was changed to something like "Antora Demo on RTD" so search engines don't start thinking this is the actual Antora Docs.

This comment has been minimized.

Sign in to view

Copy link
@man-chi

man-chi Feb 2, 2024

make sense, let me change title to be ""Antora Demo on RTD" in tutorial-template-antora

This comment has been minimized.

Sign in to view

Copy link
@humitos

humitos Feb 2, 2024

Author Member

Cool, I changed this in 44d0a73
start_page: component-b::index.adoc
content:
sources:
- url: https://gitlab.com/antora/demo/demo-component-a.git
branches: HEAD
- url: https://gitlab.com/antora/demo/demo-component-b.git
branches: [v2.0, v1.0]
start_path: docs
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true
13 changes: 0 additions & 13 deletions docs/conf.py
View file

This file was deleted.

6 changes: 0 additions & 6 deletions docs/conf.rst
View file

This file was deleted.

9 changes: 0 additions & 9 deletions docs/contents.rst
View file

This file was deleted.

29 changes: 0 additions & 29 deletions docs/index.rst
View file

This file was deleted.

0 comments on commit 5118fdf

Please sign in to comment.