Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Asciidoctor support #505

Closed
nik9000 opened this issue Dec 12, 2018 · 12 comments
Closed

Asciidoctor support #505

nik9000 opened this issue Dec 12, 2018 · 12 comments
Assignees
@nik9000

Comments

@nik9000
Copy link
Member

nik9000 commented Dec 12, 2018 •
edited
Loading

I'm using this to track things left to do for the initial Asciidoctor support:

Archived bullets:
@bmorelli25
Copy link
Member

I wasn't able to build the APM Server documentation due to a bunch of parser errors, but the agents look lovely! Two additional things I noticed:

  • Images don't work
  • [[float]]/chunking doesn't work (this might be the same as "Table of contents doesn't explode"?)

@nik9000 nik9000 closed this as completed Dec 13, 2018
@nik9000 nik9000 reopened this Dec 13, 2018
@nik9000
Copy link
Member Author

nik9000 commented Dec 13, 2018

I wasn't able to build the APM Server documentation due to a bunch of parser errors, but the agents look lovely! Two additional things I noticed:

I've added it to my checklist!

@nik9000
Copy link
Member Author

nik9000 commented Dec 18, 2018

Pinging @clintongormley who wanted to have a look at these.

My plan was to make some asciidoctor plugins to try and smooth out the differences that I've listed.

@lcawl
Copy link
Contributor

lcawl commented Jan 31, 2019

Related to #567, I would like to use this asciidoctor functionality: https://asciidoctor.org/docs/asciidoc-writers-guide/#target-window-and-role-attributes-for-links
When I try it with the following test in the Stack Overview, however:

:linkattrs:
https://www.elastic.co/subscriptions["TEST", role="xpack"]

... it's not recognizing the role attribute. It outputs it as additional text:
image

@lcawl
Copy link
Contributor

lcawl commented Feb 1, 2019 •
edited
Loading

You might already be aware, but when I test the Kibana Guide via "docbldkb --asciidoctor --lenient", it fails as follows:

asciidoctor: WARNING: management/advanced-options.asciidoc: line 18: invalid style for paragraph: float

The above error disappears when I clean up the unnecessary float per elastic/kibana#29875

The following error persists, however:

/Users/lcawley/GitRepo/docs/resources/asciidoctor/lib/copy_images/extension.rb:50:in +': asciidoctor: FAILED: /Users/lcawley/GitRepo/kibana/docs/index.asciidoc: Failed to load AsciiDoc document - no implicit conversion of nil into Array (TypeError) from /Users/lcawley/GitRepo/docs/resources/asciidoctor/lib/copy_images/extension.rb:50:in find_source'
from /Users/lcawley/GitRepo/docs/resources/asciidoctor/lib/copy_images/extension.rb:24:in `process_block'

@lcawl
Copy link
Contributor

lcawl commented Feb 2, 2019 •
edited
Loading

Here's another issue that might be related to #541. I found it while working on elastic/stack-docs#197

The images that get added for special blocks (like IMPORTANT) are missing. For example, see:
image

When those are fixed, however, I think the Installation and Upgrade Guide is in a good state to start using Asciidoctor.

@nik9000
Copy link
Member Author

nik9000 commented Feb 2, 2019

When those are fixed, however, I think the Installation and Upgrade Guide is in a good state to start using Asciidoctor.

Nice! I did know about the issue but hadn't added it to the list. I don't really have an excuse. I just suck it in my head. Anyway. I'm glad to know that is working well there.

The following error persists, however

Yikes! That is in my code. I'll add it to the list as well.

@nik9000
Copy link
Member Author

nik9000 commented Feb 4, 2019

The following error persists, however:

@lcawl that error ought to be gone now that we have #570, but I've opened #574 to improve the error handling it to be double sure.

@nik9000 nik9000 mentioned this issue Feb 8, 2019
Closed
@nik9000 nik9000 self-assigned this Feb 21, 2019
@lcawl
Copy link
Contributor

lcawl commented Feb 26, 2019 •
edited
Loading

The Stack Overview build (using the alias in #649) is failing now:

INFO:build_docs:/out/html_docs/index.xml:6534: element callout: validity error : Syntax of value for attribute arearefs of callout is not valid

Nevermind, I was able to debug the cause with the --lenient parameter. It's related to callouts and mismatched separators.

@lcawl
Copy link
Contributor

lcawl commented Feb 27, 2019 •
edited
Loading

I hadn't tested building the X-Pack Reference until now: #653

It's failing with the following errors:

Lisas-MBP-2:GitRepo lcawley$ docbldx --open --lenient
INFO:docker build:Building the docker image that will build the docs. Expect this to take somewhere between a hundred milliseconds and five minutes.
INFO:build_docs:Building HTML from /doc/x-pack/docs/en/index.asciidoc
INFO:build_docs:
INFO:build_docs:asciidoctor: ERROR: index.asciidoc: line 22: include file not found: /doc/elasticsearch-extra/x-pack-elasticsearch/docs/en/security/index.asciidoc
INFO:build_docs:asciidoctor: ERROR: index.asciidoc: line 26: include file not found: /doc/elasticsearch-extra/x-pack-elasticsearch/docs/en/watcher/index.asciidoc
INFO:build_docs:asciidoctor: ERROR: index.asciidoc: line 28: include file not found: /doc/elasticsearch-extra/x-pack-elasticsearch/docs/en/ml/index.asciidoc

Those errors remind me of the problems we had earlier with the --resource paths, but I can't find the relevant PR. Is it #601 ? Alternatively, they might be related to the fact that these x-pack-elasticsearch and x-pack-kibana repos exist under *-extra folders.

@nik9000
Copy link
Member Author

nik9000 commented Feb 27, 2019 via email

@lcawl lcawl mentioned this issue Mar 4, 2019
Merged
This was referenced Mar 14, 2019
Closed
Open
@nik9000 nik9000 mentioned this issue Oct 17, 2019
Merged
@nik9000
Copy link
Member Author

nik9000 commented Nov 5, 2019

All done!

@nik9000 nik9000 closed this as completed Nov 5, 2019
chriscressman added a commit to chriscressman/elastic-docs that referenced this issue Nov 27, 2019
@chriscressman
Remove lingering Asciidoc (Python) reference from README
ce9800c 
The Elastic doc toolchain migrated from the original Python Asciidoc
to Asciidoctor, a re-implementation in Ruby (tracked in elastic#505).

During the migration, the README referenced both Asciidoc and
Asciidoctor. After the migration, elastic#1414 removed all references to the
original Asciidoc and standardized the README on Asciidoctor. However, I
found one lingering reference to the days when both tools were being
used.

Remove a reference to the obsolete `--asciidoctor` command line option
and a note about Asciidoc vs Asciidoctor.
@chriscressman chriscressman mentioned this issue Nov 27, 2019
Merged
nik9000 pushed a commit that referenced this issue Nov 27, 2019
@chriscressman @nik9000
Remove lingering Asciidoc (Python) reference from README (#1479)
4d76352 
The Elastic doc toolchain migrated from the original Python Asciidoc
to Asciidoctor, a re-implementation in Ruby (tracked in #505).

During the migration, the README referenced both Asciidoc and
Asciidoctor. After the migration, #1414 removed all references to the
original Asciidoc and standardized the README on Asciidoctor. However, I
found one lingering reference to the days when both tools were being
used.

Remove a reference to the obsolete `--asciidoctor` command line option
and a note about Asciidoc vs Asciidoctor.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@nik9000 nik9000

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@nik9000 @bmorelli25 @lcawl