weixin_39637921
weixin_39637921
2020-12-09 14:29

Asciidoctor support

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

  • [x] Build docs with Asciidoctor when running --all
  • [x] Installation and Upgrade Guide (#629)
    • [x] The overview page has a different name. Oddly, it looks like asciidoctor is doing the right thing here. I think we can correct this when when we cut over.
  • [x] Getting Started (#645)
    • [x] Fix crashing preprocessor when it hits a skipped line #643
    • [x] ID generation doesn't quite line up (see above)
  • [x] Glossary
  • [x] Stack Overview (#649)
    • [x] Prevent snippets inside definition lists from blowing up (#680)
  • [x] Deploying with Azure Marketplace and Resource Manager (ARM) template
  • [x] Elasticsearch reference (#827)
    • [x] Prepare the book (https://github.com/elastic/elasticsearch/issues/41128)
  • [x] Elasticsearch Resiliency Status (#666)
  • [x] Painless Scripting Language (#783)
    • [x] Drop inline callouts (https://github.com/elastic/elasticsearch/issues/38335)
  • [x] Elasticsearch Plugins and Integrations (#796)
  • [x] Elasticsearch Clients: Java REST Client (#780)
    • [x] Stop include-tagged from striping out spaces (#693)
  • [x] Elasticsearch Clients: Java API (#778)
  • [x] Elasticsearch Clients: JavaScript API (#701)
  • [x] Elasticsearch Clients: Groovy API (#696)
  • [x] Elasticsearch Clients: .NET API (#812)
  • [x] Elasticsearch Clients: Perl API (#685)
  • [x] Elasticsearch Clients: PHP API (#690)
  • [x] Elasticsearch Clients: Python API (#702)
  • [x] Elasticsearch Clients: Ruby API (#691)
  • [x] Elasticsearch Clients: Community Contributed Clients (#692)
  • [x] Elasticsearch for Apache Hadoop and Spark (#785)
    • [x] Drop inline callouts (https://github.com/elastic/elasticsearch-hadoop/pull/1270)
    • [x] Handle index.adoc (#709)
  • [x] Curator Index Management (#835)
  • [x] Cloud: Elasticsearch Service - Hosted Elasticsearch and Kibana
    • [x] Drop inline callouts
  • [x] Elasticsearch Add-On for Heroku - Hosted Elasticsearch and Kibana for Heroku Users
    • [x] Drop inline callouts
  • [x] Cloud Enterprise - Elastic Cloud on your Infrastructure
    • [x] Drop inline callouts
  • [x] Kibana Reference (#756)
  • [x] Uptime Monitoring Guide (#1322)
  • [x] Logstash: Reference (#1005)
  • [x] Logstash Versioned Plugin Reference (#822)
    • [x] Clean up markdown leaks
  • [x] Beats Platform Reference
  • [x] Beats Developer Guide
  • [x] Packetbeat Reference
  • [x] Filebeat Reference
  • [x] Winlogbeat Reference
  • [x] Metricbeat Reference
  • [x] Heartbeat Reference
  • [x] Auditbeat Reference
  • [x] Functionbeat Reference
  • [x] Journalbeat Reference
  • [x] Legacy Topbeat Reference
  • [x] Site Search Reference (#1281)
  • [x] App Search Reference (#1281)
  • [x] Infrastructure Monitoring Guide (#698)
  • [x] APM Overview (#733)
  • [x] APM Server Reference (#1083)
    • [x] Figure out what to do about complex conditionals
  • [x] APM Node.js Agent (#724)
  • [x] APM Python Agent (#723)
  • [x] APM Ruby Agent (#715)
  • [x] APM Real User Monitoring JavaScript Agent (#714)
  • [x] APM Go Agent (#710)
  • [x] APM Java Agent (#707)
  • [x] APM .NET Agent (#705)
  • [x] Elastic Common Schema (#813)
  • [x] cn《Elasticsearch 权威指南》中文版 (#1317)
  • [x] cn PHP API (#1082)
  • [x] cn Kibana 用户手册 (#1310)
  • [x] jp Elasticsearchリファレンス (#1320)
  • [x] jp Logstashリファレンス (#1319)
  • [x] jp Kibanaユーザーガイド (#1315)
  • [x] jp X-Packリファレンス (#1199)
  • [x] kr Elasticsearch 참조 (#1321)
  • [x] kr Logstash 참조 (#1318)
  • [x] kr Kibana 사용자 가이드 (#1314)
  • [x] kr X-Pack 참조 (#1311)
  • [x] X-Pack Reference for 6.0-6.2 and 5.x (#653)
  • [x] Elasticsearch - The Definitive Guide (#1309)
  • [x] Sense Editor for 4.x (#746)
  • [x] Marvel Reference for 2.x and 1.x (#842)
  • [x] Shield Reference for 2.x and 1.x (#841)
  • [x] Watcher Reference for 2.x and 1.x (#821)
  • [x] Reporting Reference for 2.x (#816)
  • [x] Graph Reference for 2.x (#814)

Archived bullets: * [x] Fix rendering issues * [x] Table of contents doesn't explode (#527) * [x] Every page starts with a section containing just a double quote (#527) * [x] "Edit me" links didn't appear (#526) * [x] Ending a page with a callout list seems to eat the next line of the next page. (#529) * [x] Some snippets aren't escaped properly generating invalid xml * [x] Some callouts aren't being recognized, causing invalid xml * [x] Some special characters such as asterisks need to be escaped, otherwise they cause valid xml (#531) * [x] Beta, experimental, et all aren't showing up (#548 + #573 + #662) * [x] Include-tagged doesn't do anything * [x] Images don't work (#541) * [x] [[float]]/chunking doesn't work (this might be the same as "Table of contents doesn't explode"?) (#527) * [x] Broken definition lists cause a crash (#540) * [x] Edit url is broken (#546) * [x] Callout icons aren't showing up (#570) * [x] Admonishments images aren't copied (#604) * [x] Kibana guide fails when copying images (#574) * [x] OPEN IN CONSOLE isn't kicking in (#627) * [x] ID generation doesn't quite line up (What's Next -> _whats_next in asciidoctor vs _what_8217_s_next in asciidoc) * We've decided we're ok with this. We'll monitor when these IDs clash and see if they are broken, but for now all of the changes are good. * [x] Clean up the XML file after we're done with it (#547) * [x] Come up with some way of being sure that the rendered results are perfect or close enough. (Done with https://github.com/elastic/docs/blob/master/integtest/html_diff)

该提问来源于开源项目:elastic/docs

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

12条回答

  • weixin_39585378 weixin_39585378 5月前

    Here's another issue that might be related to https://github.com/elastic/docs/pull/541. I found it while working on https://github.com/elastic/stack-docs/pull/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.

    点赞 评论 复制链接分享
  • weixin_39637921 weixin_39637921 5月前

    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.

    点赞 评论 复制链接分享
  • weixin_39637921 weixin_39637921 5月前

    The following error persists, however:

    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.

    点赞 评论 复制链接分享
  • weixin_39585378 weixin_39585378 5月前

    The Stack Overview build (using the alias in https://github.com/elastic/docs/pull/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.

    点赞 评论 复制链接分享
  • weixin_39585378 weixin_39585378 5月前

    I hadn't tested building the X-Pack Reference until now: https://github.com/elastic/docs/pull/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 https://github.com/elastic/docs/pull/601 ? Alternatively, they might be related to the fact that these x-pack-elasticsearch and x-pack-kibana repos exist under *-extra folders.

    点赞 评论 复制链接分享
  • weixin_39637921 weixin_39637921 5月前

    Yeah no think it is the extra thing. I'll look at it. I expect it has to do with how I mount the repos for docker.

    On Wed, Feb 27, 2019, 12:18 Lisa Cawley wrote:

    I hadn't tested building the X-Pack Reference until now: #653 https://github.com/elastic/docs/pull/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. Alternatively, they might be related to the fact that these x-pack-elasticsearch and x-pack-kibana repos exist under *-extra folders.

    — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub https://github.com/elastic/docs/issues/505#issuecomment-467950707, or mute the thread https://github.com/notifications/unsubscribe-auth/AANLouFJKrt01O25e6Tz5A0DNpCN1229ks5vRr3hgaJpZM4ZQQRi .

    点赞 评论 复制链接分享
  • weixin_39637921 weixin_39637921 5月前

    All done!

    点赞 评论 复制链接分享
  • weixin_39585378 weixin_39585378 5月前

    Related to https://github.com/elastic/docs/pull/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

    点赞 评论 复制链接分享
  • weixin_39585378 weixin_39585378 5月前

    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 https://github.com/elastic/kibana/pull/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:infind_source' from /Users/lcawley/GitRepo/docs/resources/asciidoctor/lib/copy_images/extension.rb:24:in `process_block'

    点赞 评论 复制链接分享
  • weixin_39798626 weixin_39798626 5月前

    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"?)
    点赞 评论 复制链接分享
  • weixin_39637921 weixin_39637921 5月前

    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!

    点赞 评论 复制链接分享
  • weixin_39637921 weixin_39637921 5月前

    Pinging 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.

    点赞 评论 复制链接分享

相关推荐