[
https://issues.apache.org/jira/browse/TIKA-4632?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Tim Allison updated TIKA-4632:
------------------------------
Description:
I merged the .adocs from TIKA-4625.
For hosting, Claude recommended antora, which is used by Solr (e.g.
https://solr.apache.org/guide/solr/latest/index.html) and a few other ASF
projects for converting those to static html.
Antora will give us site search and will allow for "living documentation" -
where we have json in tests/examples that we have unit tests against, that is
then imported directly into the documentation.
We can have multiple versions as the Solr manual has that are tied to specific
branches, e.g. "docs/4.0.1", which would allow updates for the 4.0.1
documentation, etc.
There's a lot still to do, but I think this makes sense.
My proposal would be to continue with our current site for 3.x, build with
antora for 4.x and then cp the target/site from antora to our site's
target/site/4.x directory and publish. Once 3.x is EOL'd we can switch over to
move to antora.
Or, maybe we switch over shortly after the 4.x release, with a link to
tika.apache.org/3.x.
To build this and see what it looks like, I quote Claude and the directions
that it generated on our Maintainers/Publishing the Site page. LOL
Options 2 and 3 are far better than option 1. I'll update that shortly.
{noformat}
To build the documentation locally:
cd docs
mvn antora:antora
The generated site will be at docs/target/site/.
Previewing the Site
Option 1: Open directly in browser
# Linux
xdg-open docs/target/site/index.html
# macOS
open docs/target/site/index.html
# Windows
start docs/target/site/index.html
Option 2: Python HTTP server (recommended for testing search and links)
cd docs/target/site
python3 -m http.server 8000
Then open http://localhost:8000 in your browser.
Option 3: Node.js HTTP server
npx http-server docs/target/site -p 8000
Then open http://localhost:8000 in your browser.
{noformat}
cc [~dep4b], who may have some experience with Antora on Solr?
was:
I merged the .adocs from TIKA-4625. Claude recommended antora, which is used by
Solr (e.g. https://solr.apache.org/guide/solr/latest/index.html) and a few
other ASF projects for converting those to static html.
Antora will give us site search and will allow for "living documentation" -
where we have json in tests/examples that we have unit tests against, that is
then imported directly into the documentation.
We can have multiple versions as the Solr manual has that are tied to specific
branches, e.g. "docs/4.0.1", which would allow updates for the 4.0.1
documentation, etc.
There's a lot still to do, but I think this makes sense.
My proposal would be to continue with our current site for 3.x, build with
antora for 4.x and then cp the target/site from antora to our site's
target/site/4.x directory and publish. Once 3.x is EOL'd we can switch over to
move to antora.
Or, maybe we switch over shortly after the 4.x release, with a link to
tika.apache.org/3.x.
To build this and see what it looks like, I quote Claude and the directions
that it generated on our Maintainers/Publishing the Site page. LOL
Options 2 and 3 are far better than option 1. I'll update that shortly.
{noformat}
To build the documentation locally:
cd docs
mvn antora:antora
The generated site will be at docs/target/site/.
Previewing the Site
Option 1: Open directly in browser
# Linux
xdg-open docs/target/site/index.html
# macOS
open docs/target/site/index.html
# Windows
start docs/target/site/index.html
Option 2: Python HTTP server (recommended for testing search and links)
cd docs/target/site
python3 -m http.server 8000
Then open http://localhost:8000 in your browser.
Option 3: Node.js HTTP server
npx http-server docs/target/site -p 8000
Then open http://localhost:8000 in your browser.
{noformat}
cc [~dep4b], who may have some experience with Antora on Solr?
> Experiment with Antora for publishing adocs in 4.x
> --------------------------------------------------
>
> Key: TIKA-4632
> URL: https://issues.apache.org/jira/browse/TIKA-4632
> Project: Tika
> Issue Type: Task
> Reporter: Tim Allison
> Priority: Minor
>
> I merged the .adocs from TIKA-4625.
> For hosting, Claude recommended antora, which is used by Solr (e.g.
> https://solr.apache.org/guide/solr/latest/index.html) and a few other ASF
> projects for converting those to static html.
> Antora will give us site search and will allow for "living documentation" -
> where we have json in tests/examples that we have unit tests against, that is
> then imported directly into the documentation.
> We can have multiple versions as the Solr manual has that are tied to
> specific branches, e.g. "docs/4.0.1", which would allow updates for the 4.0.1
> documentation, etc.
> There's a lot still to do, but I think this makes sense.
> My proposal would be to continue with our current site for 3.x, build with
> antora for 4.x and then cp the target/site from antora to our site's
> target/site/4.x directory and publish. Once 3.x is EOL'd we can switch over
> to move to antora.
> Or, maybe we switch over shortly after the 4.x release, with a link to
> tika.apache.org/3.x.
> To build this and see what it looks like, I quote Claude and the directions
> that it generated on our Maintainers/Publishing the Site page. LOL
> Options 2 and 3 are far better than option 1. I'll update that shortly.
> {noformat}
> To build the documentation locally:
> cd docs
> mvn antora:antora
> The generated site will be at docs/target/site/.
> Previewing the Site
> Option 1: Open directly in browser
> # Linux
> xdg-open docs/target/site/index.html
> # macOS
> open docs/target/site/index.html
> # Windows
> start docs/target/site/index.html
> Option 2: Python HTTP server (recommended for testing search and links)
> cd docs/target/site
> python3 -m http.server 8000
> Then open http://localhost:8000 in your browser.
> Option 3: Node.js HTTP server
> npx http-server docs/target/site -p 8000
> Then open http://localhost:8000 in your browser.
> {noformat}
> cc [~dep4b], who may have some experience with Antora on Solr?
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
