From aadaecae3f5d88d493c980f25ee8d9d90213373e Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 19 Mar 2025 11:54:05 -0500 Subject: [PATCH 1/9] add code comments with context --- src/docs-assembler/navigation.yml | 32 +++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index e1731048f..cbea57adf 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -219,14 +219,46 @@ toc: path_prefix: reference/ingestion-tools children: # I don't know (TODO discuss with Colleen) + + # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we move + # reference/ingestion-tools/enrich-processor/toc.yml to + # reference/enrich-processor/toc.yml AND move all the related Markdown files from + # reference/ingestion-tools/enrich-processor/*.md to + # reference/enrich-processor/*.md + # + # If we merge that PR, would that remove the need for this item? - toc: elasticsearch://reference/ingestion-tools/enrich-processor path_prefix: reference/elasticsearch/enrich-processor + + # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we move + # reference/ingestion-tools/search-connectors/toc.yml to + # reference/search-connectors/toc.yml AND move all the related Markdown files from + # reference/ingestion-tools/search-connectors/*.md to + # reference/search-connectors/*.md + # + # If we merge that PR, would that remove the need for this item? - toc: elasticsearch://reference/ingestion-tools/search-connectors path_prefix: reference/elasticsearch/search-connectors + + # I'm not sure what's going on with this one because there is no + # toc.yml in reference/elasticsearch/data-analysis/* on `main`. + # Currently these pages are captured in the higher level reference/toc.yml. + # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we remove + # reference/toc.yml and distribute the contents across 9 individual toc.yml files. - toc: elasticsearch://reference/data-analysis path_prefix: reference/elasticsearch/data-analysis + + # This makes sense for now. I'm not sure when these files will be + # moved to https://github.com/elastic/detection-rules. - toc: security-docs://reference/prebuilt-rules path_prefix: reference/prebuilt-rules + + # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we remove + # reference/toc.yml altogether because the contents of that file will be + # distributed across 9 individual toc.yml files in subdirectories alongside the + # related Markdown files. + # + # If we merge that PR, would that remove the need for this item? - toc: elasticsearch://reference path_prefix: reference/elasticsearch From edd8c05b60ab893b9207991b9a08c650f472fbea Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 19 Mar 2025 12:00:54 -0500 Subject: [PATCH 2/9] address feedback from @lcawl @bmorelli25 in https://github.com/elastic/docs-projects/pull/464 --- src/docs-assembler/navigation.yml | 36 +++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index cbea57adf..5b5687670 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -174,7 +174,7 @@ toc: # JavaScript # ✅ https://github.com/elastic/elasticsearch-js/blob/main/docs/reference/toc.yml - toc: elasticsearch-js://reference - path_prefix: reference/elasticsearch/clients/js + path_prefix: reference/elasticsearch/clients/javascript # Children include the entire AsciiDoc book # .NET @@ -192,7 +192,7 @@ toc: # Python # ✅ https://github.com/elastic/elasticsearch-py/blob/main/docs/reference/toc.yml - toc: elasticsearch-py://reference - path_prefix: reference/elasticsearch/clients/py + path_prefix: reference/elasticsearch/clients/python # Children include the entire AsciiDoc book # Ruby @@ -204,14 +204,14 @@ toc: # Rust # ✅ https://github.com/elastic/elasticsearch-rs/blob/main/docs/reference/toc.yml - toc: elasticsearch-rs://reference - path_prefix: reference/elasticsearch/clients/rs + path_prefix: reference/elasticsearch/clients/rust # Children include the entire AsciiDoc book # Community-contributed clients # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/community-contributed/toc.yml - toc: elasticsearch://reference/community-contributed - path_prefix: reference/elasticsearch/clients/community-contributed + path_prefix: reference/elasticsearch/clients/community # Ingestion tools # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/ingestion-tools/toc.yml @@ -372,16 +372,30 @@ toc: path_prefix: reference/logstash # Children include the entire AsciiDoc book - # Logstash plugins - # 📝 TO DO: Migrate all files and create toc.yml - - toc: logstash-docs://reference - path_prefix: reference/logstash/plugins - # Children include the entire AsciiDoc book + # Commenting out because these don't exist yet!! + # 📝 TO DO: Get @karenzone's thoughts + # + # # Logstash plugins (LSR) + # # 📝 TO DO: Migrate all files and create toc.yml + # - toc: logstash-docs-md://lsr + # path_prefix: reference/logstash/plugins + # # Children include the entire AsciiDoc book + + # # Logstash versioned plugins (VPR) + # # 📝 TO DO: Migrate all files and create toc.yml + # - toc: logstash-docs-md://vpr + # path_prefix: reference/logstash/versioned-plugins + # # Children include the entire AsciiDoc book # Elastic Serverless Forwarder for AWS # ✅ https://github.com/elastic/elastic-serverless-forwarder/blob/main/docs/reference/toc.yml + # 📝 TO DO: Answer the question below + # This is the first URL that has "serverless" in the path. It's + # https://www.elastic.co/guide/en/esf/current/aws-elastic-serverless-forwarder.html + # so not really the first thing we want folks to land on if path has a lot of impact + # on search results. @KOTungseth WDYT? - toc: elastic-serverless-forwarder://reference - path_prefix: reference/elastic-serverless-forwarder + path_prefix: reference/aws-forwarder # Children include the entire AsciiDoc book # Search connectors @@ -413,7 +427,7 @@ toc: # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/elasticsearch-plugins/toc.yml - toc: elasticsearch://reference/elasticsearch-plugins - path_prefix: reference/elasticsearch-plugins + path_prefix: reference/elasticsearch/plugins # Query languages # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down From 417f7af53a14c57d3e7363d1e67cc9ca7f3b9dd2 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 19 Mar 2025 12:04:54 -0500 Subject: [PATCH 3/9] add release notes config from @KOTungseth --- src/docs-assembler/assembler.yml | 1 + src/docs-assembler/navigation.yml | 156 ++++++++++++++++++++---------- 2 files changed, 105 insertions(+), 52 deletions(-) diff --git a/src/docs-assembler/assembler.yml b/src/docs-assembler/assembler.yml index 111108acc..f17315c7e 100644 --- a/src/docs-assembler/assembler.yml +++ b/src/docs-assembler/assembler.yml @@ -35,6 +35,7 @@ references: skip: true apm-aws-lambda: apm-k8s-attacher: + apm-server: beats: skip: true cloud-on-k8s: diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index 5b5687670..cafe1b582 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -37,60 +37,112 @@ toc: ################# # RELEASE NOTES # ################# - # I didn't touch this section (yet?) - toc: release-notes children: - # repo is short for - # - toc: :// - # path_prefix: / - - repo: asciidocalypse - - repo: apm-agent-android - - repo: apm-agent-dotnet - - repo: apm-agent-go - - repo: apm-agent-ios - - repo: apm-agent-java - - repo: apm-agent-nodejs - - repo: apm-agent-php - - repo: apm-agent-python - - repo: apm-agent-ruby - - repo: apm-agent-rum-js - - repo: apm-aws-lambda - - repo: apm-k8s-attacher - - repo: beats - - repo: cloud-on-k8s - - repo: cloud - - repo: curator - - repo: ecctl - - repo: ecs-dotnet - - repo: ecs-logging-go-logrus - - repo: ecs-logging-go-zap - - repo: ecs-logging-go-zerolog - - repo: ecs-logging-java - - repo: ecs-logging-nodejs - - repo: ecs-logging-php - - repo: ecs-logging-python - - repo: ecs-logging-ruby - - repo: ecs-logging - - repo: ecs - - repo: eland - - repo: elastic-serverless-forwarder - - repo: elasticsearch-hadoop - - repo: elasticsearch-java - - repo: elasticsearch-js - - repo: elasticsearch-net - - repo: elasticsearch-php - - repo: elasticsearch-py - - repo: elasticsearch-rs - - repo: elasticsearch-ruby - - repo: elasticsearch - - repo: go-elasticsearch - - repo: integrations - - repo: kibana - - repo: logstash-docs - - repo: logstash - - repo: search-ui - - repo: integration-docs - - repo: security-docs + # Elasticsearch + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/release-notes/toc.yml + - toc: elasticsearch://release-notes + path_prefix: release-notes/elasticsearch + children: + # Elasticsearch Java Client + # ✅ https://github.com/elastic/elasticsearch-java/blob/main/docs/release-notes/toc.yml + - toc: elasticsearch-java://release-notes + path_prefix: release-notes/elasticsearch-java-client + + # Elasticsearch JavaScript Client + # ✅ https://github.com/elastic/elasticsearch-js/blob/main/docs/release-notes/toc.yml + - toc: elasticsearch-js://release-notes + path_prefix: release-notes/elasticsearch-javascript-client + + # Elasticserch PHP Client + # ✅ https://github.com/elastic/elasticsearch-php/blob/main/docs/release-notes/toc.yml + - toc: elasticsearch-php://release-notes + path_prefix: release-notes/elasticsearch-php-client + + # Elasticserch Python Client + # ✅ https://github.com/elastic/elasticsearch-py/blob/main/docs/release-notes/toc.yml + - toc: elasticsearch-py://release-notes + path_prefix: release-notes/elasticsearch-python-client + + # Kibana + # ✅ https://github.com/elastic/kibana/blob/main/docs/release-notes/toc.yml + - toc: kibana://release-notes + path_prefix: release-notes/kibana + + # Logstash + # ✅ https://github.com/elastic/logstash/blob/main/docs/release-notes/toc.yml + - toc: logstash://release-notes + path_prefix: release-notes/logstash + + # Beats + # ✅ https://github.com/elastic/beats/blob/main/docs/release-notes/toc.yml + - toc: beats://release-notes + path_prefix: release-notes/beats + + # Fleet and Elastic Agent + # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/fleet-elastic-agent/toc.yml + - toc: docs-content://release-notes/fleet-elastic-agent + path_prefix: release-notes/fleet-elastic-agent + + # Elastic Cloud Hosted + # ✅ https://github.com/elastic/cloud/blob/master/docs/release-notes/cloud-hosted/toc.yml + - toc: cloud://release-notes/cloud-hosted + path_prefix: release-notes/elastic-cloud-hosted + + # Elastic Cloud Serverless + # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-cloud-serverless/toc.yml + - toc: docs-content://release-notes/elastic-cloud-serverless + path_prefix: release-notes/elastic-cloud-serverless + + # Elastic Cloud Enterprise + # ✅ https://github.com/elastic/cloud/blob/master/docs/release-notes/cloud-hosted/toc.yml + - toc: cloud://release-notes/cloud-enterprise + path_prefix: release-notes/elastic-cloud-enterprise + + # Elastic Cloud on Kubernetes + # ✅ https://github.com/elastic/cloud-on-k8s/blob/main/docs/release-notes/toc.yml + - toc: cloud-on-k8s://release-notes + path_prefix: release-notes/elastic-cloud-kubernetes + + # Elastic Observability + # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-observability/toc.yml + - toc: docs-content://release-notes/elastic-observability + path_prefix: release-notes/elastic-observability + children: + # Elastic APM + # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-apm/toc.yml + - toc: apm-server://release-notes + path_prefix: release-notes/elastic-apm + + # Elastic APM .NET Agent + # ✅ https://github.com/elastic/apm-agent-dotnet/blob/main/docs/release-notes/toc.yml + - toc: apm-agent-dotnet://release-notes + path_prefix: release-notes/elastic-apm-net-agent + + # Elastic APM Go Agent + # ✅ https://github.com/elastic/apm-agent-go/blob/main/docs/release-notes/toc.yml + - toc: apm-agent-go://release-notes + path_prefix: release-notes/elastic-apm-go-agent + + # Elastic APM iOS Agent + # ✅ https://github.com/elastic/apm-agent-ios/blob/main/docs/release-notes/toc.yml + - toc: apm-agent-ios://release-notes + path_prefix: release-notes/elastic-apm-ios-agent + + # Elastic APM Ruby Agent + # https://github.com/elastic/apm-agent-ruby/blob/main/docs/release-notes/toc.yml + - toc: apm-agent-ruby://release-notes + path_prefix: release-notes/elastic-apm-ruby-agent + + # Elastic APM RUM JavaScript Agent + # ✅ https://github.com/elastic/apm-agent-rum-js/blob/main/docs/release-notes/toc.yml + - toc: apm-agent-rum-js://release-notes + path_prefix: release-notes/elastic-apm-rum-javascript-agent + + # Elastic Security + # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-security/toc.yml + - toc: docs-content://release-notes/elastic-security + path_prefix: release-notes/elastic-security ############# # REFERENCE # From 289333f629b05c3e6b791675f0d4fa2e493e0b10 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 19 Mar 2025 13:38:37 -0500 Subject: [PATCH 4/9] Revert "add release notes config from @KOTungseth" This reverts commit 417f7af53a14c57d3e7363d1e67cc9ca7f3b9dd2. --- src/docs-assembler/assembler.yml | 1 - src/docs-assembler/navigation.yml | 156 ++++++++++-------------------- 2 files changed, 52 insertions(+), 105 deletions(-) diff --git a/src/docs-assembler/assembler.yml b/src/docs-assembler/assembler.yml index f17315c7e..111108acc 100644 --- a/src/docs-assembler/assembler.yml +++ b/src/docs-assembler/assembler.yml @@ -35,7 +35,6 @@ references: skip: true apm-aws-lambda: apm-k8s-attacher: - apm-server: beats: skip: true cloud-on-k8s: diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index cafe1b582..5b5687670 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -37,112 +37,60 @@ toc: ################# # RELEASE NOTES # ################# + # I didn't touch this section (yet?) - toc: release-notes children: - # Elasticsearch - # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/release-notes/toc.yml - - toc: elasticsearch://release-notes - path_prefix: release-notes/elasticsearch - children: - # Elasticsearch Java Client - # ✅ https://github.com/elastic/elasticsearch-java/blob/main/docs/release-notes/toc.yml - - toc: elasticsearch-java://release-notes - path_prefix: release-notes/elasticsearch-java-client - - # Elasticsearch JavaScript Client - # ✅ https://github.com/elastic/elasticsearch-js/blob/main/docs/release-notes/toc.yml - - toc: elasticsearch-js://release-notes - path_prefix: release-notes/elasticsearch-javascript-client - - # Elasticserch PHP Client - # ✅ https://github.com/elastic/elasticsearch-php/blob/main/docs/release-notes/toc.yml - - toc: elasticsearch-php://release-notes - path_prefix: release-notes/elasticsearch-php-client - - # Elasticserch Python Client - # ✅ https://github.com/elastic/elasticsearch-py/blob/main/docs/release-notes/toc.yml - - toc: elasticsearch-py://release-notes - path_prefix: release-notes/elasticsearch-python-client - - # Kibana - # ✅ https://github.com/elastic/kibana/blob/main/docs/release-notes/toc.yml - - toc: kibana://release-notes - path_prefix: release-notes/kibana - - # Logstash - # ✅ https://github.com/elastic/logstash/blob/main/docs/release-notes/toc.yml - - toc: logstash://release-notes - path_prefix: release-notes/logstash - - # Beats - # ✅ https://github.com/elastic/beats/blob/main/docs/release-notes/toc.yml - - toc: beats://release-notes - path_prefix: release-notes/beats - - # Fleet and Elastic Agent - # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/fleet-elastic-agent/toc.yml - - toc: docs-content://release-notes/fleet-elastic-agent - path_prefix: release-notes/fleet-elastic-agent - - # Elastic Cloud Hosted - # ✅ https://github.com/elastic/cloud/blob/master/docs/release-notes/cloud-hosted/toc.yml - - toc: cloud://release-notes/cloud-hosted - path_prefix: release-notes/elastic-cloud-hosted - - # Elastic Cloud Serverless - # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-cloud-serverless/toc.yml - - toc: docs-content://release-notes/elastic-cloud-serverless - path_prefix: release-notes/elastic-cloud-serverless - - # Elastic Cloud Enterprise - # ✅ https://github.com/elastic/cloud/blob/master/docs/release-notes/cloud-hosted/toc.yml - - toc: cloud://release-notes/cloud-enterprise - path_prefix: release-notes/elastic-cloud-enterprise - - # Elastic Cloud on Kubernetes - # ✅ https://github.com/elastic/cloud-on-k8s/blob/main/docs/release-notes/toc.yml - - toc: cloud-on-k8s://release-notes - path_prefix: release-notes/elastic-cloud-kubernetes - - # Elastic Observability - # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-observability/toc.yml - - toc: docs-content://release-notes/elastic-observability - path_prefix: release-notes/elastic-observability - children: - # Elastic APM - # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-apm/toc.yml - - toc: apm-server://release-notes - path_prefix: release-notes/elastic-apm - - # Elastic APM .NET Agent - # ✅ https://github.com/elastic/apm-agent-dotnet/blob/main/docs/release-notes/toc.yml - - toc: apm-agent-dotnet://release-notes - path_prefix: release-notes/elastic-apm-net-agent - - # Elastic APM Go Agent - # ✅ https://github.com/elastic/apm-agent-go/blob/main/docs/release-notes/toc.yml - - toc: apm-agent-go://release-notes - path_prefix: release-notes/elastic-apm-go-agent - - # Elastic APM iOS Agent - # ✅ https://github.com/elastic/apm-agent-ios/blob/main/docs/release-notes/toc.yml - - toc: apm-agent-ios://release-notes - path_prefix: release-notes/elastic-apm-ios-agent - - # Elastic APM Ruby Agent - # https://github.com/elastic/apm-agent-ruby/blob/main/docs/release-notes/toc.yml - - toc: apm-agent-ruby://release-notes - path_prefix: release-notes/elastic-apm-ruby-agent - - # Elastic APM RUM JavaScript Agent - # ✅ https://github.com/elastic/apm-agent-rum-js/blob/main/docs/release-notes/toc.yml - - toc: apm-agent-rum-js://release-notes - path_prefix: release-notes/elastic-apm-rum-javascript-agent - - # Elastic Security - # ✅ https://github.com/elastic/docs-content/blob/main/release-notes/elastic-security/toc.yml - - toc: docs-content://release-notes/elastic-security - path_prefix: release-notes/elastic-security + # repo is short for + # - toc: :// + # path_prefix: / + - repo: asciidocalypse + - repo: apm-agent-android + - repo: apm-agent-dotnet + - repo: apm-agent-go + - repo: apm-agent-ios + - repo: apm-agent-java + - repo: apm-agent-nodejs + - repo: apm-agent-php + - repo: apm-agent-python + - repo: apm-agent-ruby + - repo: apm-agent-rum-js + - repo: apm-aws-lambda + - repo: apm-k8s-attacher + - repo: beats + - repo: cloud-on-k8s + - repo: cloud + - repo: curator + - repo: ecctl + - repo: ecs-dotnet + - repo: ecs-logging-go-logrus + - repo: ecs-logging-go-zap + - repo: ecs-logging-go-zerolog + - repo: ecs-logging-java + - repo: ecs-logging-nodejs + - repo: ecs-logging-php + - repo: ecs-logging-python + - repo: ecs-logging-ruby + - repo: ecs-logging + - repo: ecs + - repo: eland + - repo: elastic-serverless-forwarder + - repo: elasticsearch-hadoop + - repo: elasticsearch-java + - repo: elasticsearch-js + - repo: elasticsearch-net + - repo: elasticsearch-php + - repo: elasticsearch-py + - repo: elasticsearch-rs + - repo: elasticsearch-ruby + - repo: elasticsearch + - repo: go-elasticsearch + - repo: integrations + - repo: kibana + - repo: logstash-docs + - repo: logstash + - repo: search-ui + - repo: integration-docs + - repo: security-docs ############# # REFERENCE # From 75267df1a1d0803f2d24edce9fb40dda0198bacd Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Wed, 19 Mar 2025 14:03:02 -0500 Subject: [PATCH 5/9] net -> dotnet --- src/docs-assembler/navigation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index 5b5687670..90234cf2e 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -180,7 +180,7 @@ toc: # .NET # ✅ https://github.com/elastic/elasticsearch-net/blob/main/docs/reference/toc.yml - toc: elasticsearch-net://reference - path_prefix: reference/elasticsearch/clients/net + path_prefix: reference/elasticsearch/clients/dotnet # Children include the entire AsciiDoc book # PHP From e9ed222e4d50fb0337ef5ce37d2984e8f82bfc74 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 21 Mar 2025 13:24:21 -0500 Subject: [PATCH 6/9] update navigation.yml and assembler.yml --- src/docs-assembler/assembler.yml | 11 +-- src/docs-assembler/navigation.yml | 153 +++++++++++++----------------- 2 files changed, 66 insertions(+), 98 deletions(-) diff --git a/src/docs-assembler/assembler.yml b/src/docs-assembler/assembler.yml index ed3576daa..3aa7d2c3d 100644 --- a/src/docs-assembler/assembler.yml +++ b/src/docs-assembler/assembler.yml @@ -26,19 +26,14 @@ references: apm-agent-ios: apm-agent-java: apm-agent-nodejs: - skip: true apm-agent-php: - skip: true apm-agent-python: - skip: true apm-agent-ruby: - skip: true apm-agent-rum-js: - skip: true apm-aws-lambda: apm-k8s-attacher: + apm-server: beats: - skip: true cloud-on-k8s: cloud: current: master @@ -60,7 +55,6 @@ references: ecs-logging-ruby: ecs-logging: ecs: - skip: true eland: elastic-serverless-forwarder: elasticsearch-hadoop: @@ -79,10 +73,9 @@ references: go-elasticsearch: integrations: kibana: - logstash-docs: + logstash-docs-md: skip: true logstash: - skip: true search-ui: integration-docs: skip: true diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index ad76615da..d1e9aaa3e 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -57,6 +57,7 @@ toc: - repo: apm-agent-rum-js - repo: apm-aws-lambda - repo: apm-k8s-attacher + - repo: apm-server - repo: beats - repo: cloud-on-k8s - repo: cloud @@ -99,27 +100,27 @@ toc: - toc: reference children: # Security - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/security/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/security/toc.yml - toc: docs-content://reference/security path_prefix: reference/security # Children include: Endpoint command reference, Elastic Defend, # Fields and object schemas children: - # 📝 TO DO: I don't remember the repo name - # 📝 TO DO: toc.yml needs to be created - - toc: that-other-sec-repo://reference + # 📝 TO DO: Update when rules are moved to elastic/detection-rules + # This makes sense for now. I'm not sure when these files will be + # moved to https://github.com/elastic/detection-rules. + - toc: security-docs://reference/prebuilt-rules path_prefix: reference/security/prebuilt-rules - # Children include the entire AsciiDoc book # Observability - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/observability/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/observability/toc.yml - toc: docs-content://reference/observability path_prefix: reference/observability # Children include: Fields and object schemas, Elastic Entity Model, # Infrastructure app fields # Search - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/search/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/search/toc.yml - toc: docs-content://reference/search path_prefix: reference/search children: @@ -130,12 +131,22 @@ toc: # Children include the entire AsciiDoc book # Elasticsearch and index management - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/elasticsearch/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/elasticsearch/toc.yml - toc: docs-content://reference/elasticsearch path_prefix: reference/elasticsearch children: - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/elasticsearch/toc.yml + + # 📝 TO DO: Delete this item + # This should be replaced by: + # * `elasticsearch://reference/elasticsearch` + # * `elasticsearch://reference/community-contributed` + # * `elasticsearch://reference/elasticsearch-plugins` + # * `elasticsearch://reference/query-languages` + # * `elasticsearch://reference/scripting-languages` + - toc: elasticsearch://reference + path_prefix: reference/elasticsearch + + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/toc.yml - toc: elasticsearch://reference/elasticsearch path_prefix: reference/elasticsearch # Children include: Configuration, JVM settings, Roles, @@ -149,8 +160,8 @@ toc: # Children include the entire AsciiDoc book # Clients - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/elasticsearch-clients/toc.yml - - toc: docs-content://reference/elasticsearch/clients + # ✅ https://github.com/elastic/docs-content/blob/main/reference/elasticsearch-clients/toc.yml + - toc: docs-content://reference/elasticsearch-clients path_prefix: reference/elasticsearch/clients children: @@ -209,68 +220,23 @@ toc: # Children include the entire AsciiDoc book # Community-contributed clients - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/community-contributed/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/community-contributed/toc.yml - toc: elasticsearch://reference/community-contributed path_prefix: reference/elasticsearch/clients/community # Ingestion tools - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/ingestion-tools/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/ingestion-tools/toc.yml - toc: docs-content://reference/ingestion-tools path_prefix: reference/ingestion-tools children: - # I don't know (TODO discuss with Colleen) - - # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we move - # reference/ingestion-tools/enrich-processor/toc.yml to - # reference/enrich-processor/toc.yml AND move all the related Markdown files from - # reference/ingestion-tools/enrich-processor/*.md to - # reference/enrich-processor/*.md - # - # If we merge that PR, would that remove the need for this item? - - toc: elasticsearch://reference/ingestion-tools/enrich-processor - path_prefix: reference/elasticsearch/enrich-processor - - # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we move - # reference/ingestion-tools/search-connectors/toc.yml to - # reference/search-connectors/toc.yml AND move all the related Markdown files from - # reference/ingestion-tools/search-connectors/*.md to - # reference/search-connectors/*.md - # - # If we merge that PR, would that remove the need for this item? - - toc: elasticsearch://reference/ingestion-tools/search-connectors - path_prefix: reference/elasticsearch/search-connectors - - # I'm not sure what's going on with this one because there is no - # toc.yml in reference/elasticsearch/data-analysis/* on `main`. - # Currently these pages are captured in the higher level reference/toc.yml. - # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we remove - # reference/toc.yml and distribute the contents across 9 individual toc.yml files. - - toc: elasticsearch://reference/data-analysis - path_prefix: reference/elasticsearch/data-analysis - - # This makes sense for now. I'm not sure when these files will be - # moved to https://github.com/elastic/detection-rules. - - toc: security-docs://reference/prebuilt-rules - path_prefix: reference/prebuilt-rules - - # In https://github.com/elastic/elasticsearch/pull/125118 I'm proposing we remove - # reference/toc.yml altogether because the contents of that file will be - # distributed across 9 individual toc.yml files in subdirectories alongside the - # related Markdown files. - # - # If we merge that PR, would that remove the need for this item? - - toc: elasticsearch://reference - path_prefix: reference/elasticsearch - # Fleet and Elastic Agent - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/fleet/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/fleet/toc.yml - toc: docs-content://reference/fleet path_prefix: reference/fleet # Children include the entire AsciiDoc book # APM - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/apm/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/apm/toc.yml - toc: docs-content://reference/apm path_prefix: reference/apm # Children include: APM settings, APM settings for Elastic Cloud, @@ -289,7 +255,7 @@ toc: # Children include the entire AsciiDoc book # APM agents - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/apm-agents/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/apm-agents/toc.yml - toc: docs-content://reference/ingestion-tools/apm/agents path_prefix: reference/apm/agents children: @@ -324,25 +290,25 @@ toc: # Children include the entire AsciiDoc book # APM Node.js agent - # 🔜 https://github.com/colleenmcginnis/apm-agent-nodejs/blob/migrate-docs/docs/reference/toc.yml + # ✅ https://github.com/elastic/apm-agent-nodejs/blob/main/docs/reference/toc.yml - toc: apm-agent-nodejs://reference path_prefix: reference/apm/agents/nodejs # Children include the entire AsciiDoc book # APM PHP agent - # 🔜 https://github.com/colleenmcginnis/apm-agent-php/blob/migrate-docs/docs/reference/toc.yml + # ✅ https://github.com/elastic/apm-agent-php/blob/main/docs/reference/toc.yml - toc: apm-agent-php://reference path_prefix: reference/apm/agents/php # Children include the entire AsciiDoc book # APM Python agent - # 🔜 https://github.com/colleenmcginnis/apm-agent-python/blob/migrate-docs/docs/reference/toc.yml + # ✅ https://github.com/elastic/apm-agent-python/blob/main/docs/reference/toc.yml - toc: apm-agent-python://reference path_prefix: reference/apm/agents/python # Children include the entire AsciiDoc book # APM Ruby agent - # 🔜 https://github.com/colleenmcginnis/apm-agent-ruby/blob/migrate-docs/docs/reference/toc.yml + # ✅ https://github.com/elastic/apm-agent-ruby/blob/main/docs/reference/toc.yml - toc: apm-agent-ruby://reference path_prefix: reference/apm/agents/ruby # Children include the entire AsciiDoc book @@ -354,16 +320,20 @@ toc: # Children include the entire AsciiDoc book # Beats - # 🔜 https://github.com/colleenmcginnis/beats/blob/migrate-docs/docs/reference/toc.yml + # ✅ https://github.com/elastic/beats/blob/main/docs/reference/toc.yml - toc: beats://reference path_prefix: reference/beats # Children include all entire AsciiDoc books: Beats, Auditbeat, # Filebeat, Heartbeat, Metricbeat, Packetbeat, Winlogbeat, # Elastic logging plugin for Docker + # 📝 TO DO: Delete this item + # This should be replaced by `elasticsearch://reference/enrich-processor` below + - toc: elasticsearch://reference/ingestion-tools/enrich-processor + path_prefix: reference/elasticsearch/enrich-processor + # Processor reference - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/enrich-processor/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/enrich-processor/toc.yml - toc: elasticsearch://reference/enrich-processor path_prefix: reference/enrich-processor @@ -373,9 +343,8 @@ toc: path_prefix: reference/logstash # Children include the entire AsciiDoc book - # Commenting out because these don't exist yet!! - # 📝 TO DO: Get @karenzone's thoughts - # + # Commenting out because these aren't stable yet!! + # # Logstash plugins (LSR) # # 📝 TO DO: Migrate all files and create toc.yml # - toc: logstash-docs-md://lsr @@ -399,9 +368,13 @@ toc: path_prefix: reference/aws-forwarder # Children include the entire AsciiDoc book + # 📝 TO DO: Delete this item + # This should be replaced by `elasticsearch://reference/search-connectors` below + - toc: elasticsearch://reference/ingestion-tools/search-connectors + path_prefix: reference/elasticsearch/search-connectors + # Search connectors - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/search-connectors/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/search-connectors/toc.yml - toc: elasticsearch://reference/search-connectors path_prefix: reference/search-connectors @@ -412,7 +385,7 @@ toc: # Children include the entire AsciiDoc book # Elastic Integrations - # 📝 TO DO: Waiting on integration devs to support 9.0 in all integrations + # ✅ https://github.com/elastic/integration-docs/blob/main/docs/reference/toc.yml - toc: integration-docs://reference path_prefix: reference/integrations # Children include the entire AsciiDoc book @@ -425,25 +398,22 @@ toc: # (minus pages moved to docs-content) # Elasticsearch plugins - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/elasticsearch-plugins/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch-plugins/toc.yml - toc: elasticsearch://reference/elasticsearch-plugins path_prefix: reference/elasticsearch/plugins # Query languages - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/query-languages/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/query-languages/toc.yml - toc: elasticsearch://reference/query-languages path_prefix: reference/query-languages # Scripting languages - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/scripting-languages/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/scripting-languages/toc.yml - toc: elasticsearch://reference/scripting-languages path_prefix: reference/scripting-languages # ECS - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/ecs/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/ecs/toc.yml - toc: docs-content://reference/ecs path_prefix: reference/ecs children: @@ -513,23 +483,28 @@ toc: # Children include the entire AsciiDoc book # Data analysis - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/data-analysis/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/data-analysis/toc.yml - toc: docs-content://reference/data-analysis path_prefix: reference/data-analysis # Children include: Supplied configurations, Function reference, # Metrics reference, Canvas function reference children: - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/text-analysis/toc.yml + + # 📝 TO DO: Delete this item + # This should be replaced by `elasticsearch://reference/text-analysis` and + # `elasticsearch://reference/aggregations` below. + - toc: elasticsearch://reference/data-analysis + path_prefix: reference/elasticsearch/data-analysis + + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/text-analysis/toc.yml - toc: elasticsearch://reference/text-analysis path_prefix: reference/text-analysis - # 📝 TO DO: Directory depth in elasticsearch repo: would require toc 2 levels down - # 🔜 https://github.com/colleenmcginnis/elasticsearch/blob/docs-assembler-prep/docs/reference/aggregations/toc.yml + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/aggregations/toc.yml - toc: elasticsearch://reference/aggregations path_prefix: reference/aggregations # Cloud - # 📝 TO DO: toc.yml needs to be created with one file / no children + # ✅ https://github.com/elastic/docs-content/blob/main/reference/cloud/toc.yml - toc: docs-content://reference/cloud path_prefix: reference/cloud children: @@ -556,6 +531,6 @@ toc: # (minus pages moved to docs-content) # Glossary - # 🔜 https://github.com/elastic/docs-content/blob/prepare-for-assembler/reference/glossary/toc.yml + # ✅ https://github.com/elastic/docs-content/blob/main/reference/glossary/toc.yml - toc: docs-content://reference/glossary path_prefix: reference/glossary \ No newline at end of file From 405d8fb34c8a1bcb9ca3ea51e8488472ea0c7666 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 24 Mar 2025 10:07:25 -0500 Subject: [PATCH 7/9] clean up --- src/docs-assembler/assembler.yml | 23 +++++++++++------------ src/docs-assembler/navigation.yml | 30 +++++++----------------------- 2 files changed, 18 insertions(+), 35 deletions(-) diff --git a/src/docs-assembler/assembler.yml b/src/docs-assembler/assembler.yml index abcc42285..3898acbd7 100644 --- a/src/docs-assembler/assembler.yml +++ b/src/docs-assembler/assembler.yml @@ -30,17 +30,16 @@ references: apm-agent-rum-js: apm-aws-lambda: apm-k8s-attacher: - apm-server: beats: cloud-on-k8s: cloud: current: master - curator: - skip: true - current: master - ecctl: - current: master - skip: true + # curator: + # skip: true + # current: master + # ecctl: + # current: master + # skip: true ecs-dotnet: ecs-logging-go-logrus: ecs-logging-go-zap: @@ -61,8 +60,8 @@ references: elasticsearch-php: elasticsearch-py: # https://github.com/elastic/elasticsearch-rs ci checks not running? - elasticsearch-rs: - skip: true + # elasticsearch-rs: + # skip: true elasticsearch-ruby: elasticsearch: go-elasticsearch: @@ -73,6 +72,6 @@ references: logstash: search-ui: integration-docs: - security-docs: - # wait for move to https://github.com/elastic/detection-rules/pull/4507/files - skip: true + # security-docs: + # # wait for move to https://github.com/elastic/detection-rules/pull/4507/files + # skip: true diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index 9bf2487f8..aac5bd1f2 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -133,12 +133,12 @@ toc: # Elasticsearch and index management # ✅ https://github.com/elastic/docs-content/blob/main/reference/elasticsearch/toc.yml - toc: docs-content://reference/elasticsearch - path_prefix: reference/elasticsearch + path_prefix: reference/elasticsearch/overview children: # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/toc.yml - #- toc: elasticsearch://reference/elasticsearch - # path_prefix: reference/elasticsearch + - toc: elasticsearch://reference/elasticsearch + path_prefix: reference/elasticsearch # Children include: Configuration, JVM settings, Roles, # Elasticsearch privileges, Index settings, Index lifecycle actions, # REST APIs, Mapping, Elasticsearch audit events, Command line tools @@ -318,11 +318,6 @@ toc: # Filebeat, Heartbeat, Metricbeat, Packetbeat, Winlogbeat, # Elastic logging plugin for Docker - # 📝 TO DO: Delete this item - # This should be replaced by `elasticsearch://reference/enrich-processor` below - - toc: elasticsearch://reference/ingestion-tools/enrich-processor - path_prefix: reference/elasticsearch/enrich-processor - # Processor reference # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/enrich-processor/toc.yml - toc: elasticsearch://reference/enrich-processor @@ -359,11 +354,6 @@ toc: path_prefix: reference/aws-forwarder # Children include the entire AsciiDoc book - # 📝 TO DO: Delete this item - # This should be replaced by `elasticsearch://reference/search-connectors` below - - toc: elasticsearch://reference/ingestion-tools/search-connectors - path_prefix: reference/elasticsearch/search-connectors - # Search connectors # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/search-connectors/toc.yml - toc: elasticsearch://reference/search-connectors @@ -406,13 +396,13 @@ toc: # ECS # ✅ https://github.com/elastic/docs-content/blob/main/reference/ecs/toc.yml - toc: docs-content://reference/ecs - path_prefix: reference/ecs + path_prefix: reference/ecs/overview children: # ECS reference # ✅ https://github.com/elastic/ecs/blob/main/docs/reference/toc.yml # TODO MARTIJN conflicting path_prefix - toc: ecs://reference - path_prefix: reference/ecs/ref + path_prefix: reference/ecs # Children include the entire AsciiDoc book # ECS logging libraries @@ -482,12 +472,6 @@ toc: # Metrics reference, Canvas function reference children: - # 📝 TO DO: Delete this item - # This should be replaced by `elasticsearch://reference/text-analysis` and - # `elasticsearch://reference/aggregations` below. - - toc: elasticsearch://reference/data-analysis - path_prefix: reference/elasticsearch/data-analysis - # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/text-analysis/toc.yml - toc: elasticsearch://reference/text-analysis path_prefix: reference/text-analysis @@ -498,14 +482,14 @@ toc: # Cloud # ✅ https://github.com/elastic/docs-content/blob/main/reference/cloud/toc.yml - toc: docs-content://reference/cloud - path_prefix: reference/cloud + path_prefix: reference/cloud/overview children: # Elastic Cloud Enterprise # Elastic Cloud Hosted # ✅ https://github.com/elastic/cloud/blob/master/docs/reference/toc.yml # TODO Martijn: conflicting path_prefix - toc: cloud://reference - path_prefix: reference/cloud/ref + path_prefix: reference/cloud # Children include the entire AsciiDoc book # (minus pages moved to docs-content) From cf3fe12c44326ef31900580e3201bb8dab90378c Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Mon, 24 Mar 2025 11:01:26 -0500 Subject: [PATCH 8/9] more clean up --- src/docs-assembler/navigation.yml | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index aac5bd1f2..b774fbd24 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -131,18 +131,14 @@ toc: # Children include the entire AsciiDoc book # Elasticsearch and index management - # ✅ https://github.com/elastic/docs-content/blob/main/reference/elasticsearch/toc.yml - - toc: docs-content://reference/elasticsearch - path_prefix: reference/elasticsearch/overview + # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/toc.yml + - toc: elasticsearch://reference/elasticsearch + path_prefix: reference/elasticsearch + # Children include: Configuration, JVM settings, Roles, + # Elasticsearch privileges, Index settings, Index lifecycle actions, + # REST APIs, Mapping, Elasticsearch audit events, Command line tools children: - # ✅ https://github.com/elastic/elasticsearch/blob/main/docs/reference/elasticsearch/toc.yml - - toc: elasticsearch://reference/elasticsearch - path_prefix: reference/elasticsearch - # Children include: Configuration, JVM settings, Roles, - # Elasticsearch privileges, Index settings, Index lifecycle actions, - # REST APIs, Mapping, Elasticsearch audit events, Command line tools - # Curator # ✅ https://github.com/elastic/curator/blob/master/docs/reference/toc.yml # TODO MARTIJN: needs to run once more on master for the link index @@ -247,7 +243,7 @@ toc: # APM agents # ✅ https://github.com/elastic/docs-content/blob/main/reference/apm-agents/toc.yml - - toc: docs-content://reference/ingestion-tools/apm/agents + - toc: docs-content://reference/apm-agents path_prefix: reference/apm/agents children: # APM Android agent From ffa8980ff86dfcc5510cb329115c5ba3d0522707 Mon Sep 17 00:00:00 2001 From: Martijn Laarman Date: Mon, 24 Mar 2025 21:45:12 +0100 Subject: [PATCH 9/9] Refactor navigation handling and introduce phantom support Simplified navigation logic by restructuring method signatures and refining table of contents processing. Added support for phantom definitions in navigation files, ensuring appropriate handling of unlinked TOC folders. Refactored related classes to align with the new navigation paradigm. --- src/docs-assembler/AssembleSources.cs | 14 +++-- src/docs-assembler/Cli/RepositoryCommands.cs | 4 +- .../Navigation/GlobalNavigationFile.cs | 56 +++++++++++++----- .../Navigation/GlobalNavigationHtmlWriter.cs | 59 ++++++++----------- .../GlobalNavigationPathProvider.cs | 58 ++++-------------- src/docs-assembler/navigation.yml | 5 ++ 6 files changed, 95 insertions(+), 101 deletions(-) diff --git a/src/docs-assembler/AssembleSources.cs b/src/docs-assembler/AssembleSources.cs index 759354ef8..e747d47cb 100644 --- a/src/docs-assembler/AssembleSources.cs +++ b/src/docs-assembler/AssembleSources.cs @@ -33,6 +33,7 @@ public record TocConfigurationMapping public class AssembleSources { + public AssembleContext AssembleContext { get; } public FrozenDictionary AssembleSets { get; } public FrozenDictionary TocTopLevelMappings { get; } @@ -51,16 +52,17 @@ public static async Task AssembleAsync(AssembleContext context, return sources; } - private AssembleSources(AssembleContext context, Checkout[] checkouts) + private AssembleSources(AssembleContext assembleContext, Checkout[] checkouts) { - TocTopLevelMappings = GetConfiguredSources(context); + AssembleContext = assembleContext; + TocTopLevelMappings = GetConfiguredSources(assembleContext); - var crossLinkFetcher = new AssemblerCrossLinkFetcher(NullLoggerFactory.Instance, context.Configuration); - UriResolver = new PublishEnvironmentUriResolver(TocTopLevelMappings, context.Environment); + var crossLinkFetcher = new AssemblerCrossLinkFetcher(NullLoggerFactory.Instance, assembleContext.Configuration); + UriResolver = new PublishEnvironmentUriResolver(TocTopLevelMappings, assembleContext.Environment); var crossLinkResolver = new CrossLinkResolver(crossLinkFetcher, UriResolver); AssembleSets = checkouts .Where(c => !c.Repository.Skip) - .Select(c => new AssemblerDocumentationSet(NullLoggerFactory.Instance, context, c, crossLinkResolver, TreeCollector)) + .Select(c => new AssemblerDocumentationSet(NullLoggerFactory.Instance, assembleContext, c, crossLinkResolver, TreeCollector)) .ToDictionary(s => s.Checkout.Repository.Name, s => s) .ToFrozenDictionary(); @@ -85,7 +87,7 @@ private AssembleSources(AssembleContext context, Checkout[] checkouts) var file = tocFiles.FirstOrDefault(f => f.Exists); if (file is null) { - context.Collector.EmitWarning(context.ConfigurationPath.FullName, $"Unable to find toc file in {tocDirectory}"); + assembleContext.Collector.EmitWarning(assembleContext.ConfigurationPath.FullName, $"Unable to find toc file in {tocDirectory}"); file = tocFiles.First(); } diff --git a/src/docs-assembler/Cli/RepositoryCommands.cs b/src/docs-assembler/Cli/RepositoryCommands.cs index 4aa38f2f5..0702e228f 100644 --- a/src/docs-assembler/Cli/RepositoryCommands.cs +++ b/src/docs-assembler/Cli/RepositoryCommands.cs @@ -88,8 +88,8 @@ public async Task BuildAll( var navigation = new GlobalNavigation(assembleSources, navigationFile); - var pathProvider = new GlobalNavigationPathProvider(assembleSources, assembleContext); - var htmlWriter = new GlobalNavigationHtmlWriter(assembleContext, navigation, assembleSources); + var pathProvider = new GlobalNavigationPathProvider(navigationFile, assembleSources, assembleContext); + var htmlWriter = new GlobalNavigationHtmlWriter(navigationFile, assembleContext, navigation, assembleSources); var builder = new AssemblerBuilder(logger, assembleContext, htmlWriter, pathProvider); await builder.BuildAllAsync(assembleSources.AssembleSets, ctx); diff --git a/src/docs-assembler/Navigation/GlobalNavigationFile.cs b/src/docs-assembler/Navigation/GlobalNavigationFile.cs index 8bb62811b..ac4637b6a 100644 --- a/src/docs-assembler/Navigation/GlobalNavigationFile.cs +++ b/src/docs-assembler/Navigation/GlobalNavigationFile.cs @@ -3,6 +3,7 @@ // See the LICENSE file in the project root for more information using System.Collections.Frozen; +using System.IO.Abstractions; using Documentation.Assembler.Configuration; using Elastic.Markdown.IO.Configuration; using Elastic.Markdown.IO.Navigation; @@ -10,18 +11,23 @@ namespace Documentation.Assembler.Navigation; -public record GlobalNavigationFile +public record GlobalNavigationFile : ITableOfContentsScope { private readonly AssembleContext _context; private readonly AssembleSources _assembleSources; public IReadOnlyCollection TableOfContents { get; } + public IReadOnlyCollection Phantoms { get; } + + public IDirectoryInfo ScopeDirectory { get; } public GlobalNavigationFile(AssembleContext context, AssembleSources assembleSources) { _context = context; _assembleSources = assembleSources; - TableOfContents = Deserialize(); + TableOfContents = Deserialize("toc"); + Phantoms = Deserialize("phantoms"); + ScopeDirectory = _context.NavigationPath.Directory!; } public void EmitWarning(string message) => @@ -31,18 +37,15 @@ public void EmitError(string message) => _context.Collector.EmitWarning(_context.NavigationPath.FullName, message); - private IReadOnlyCollection Deserialize() + private IReadOnlyCollection Deserialize(string key) { var reader = new YamlStreamReader(_context.NavigationPath, _context.Collector); try { foreach (var entry in reader.Read()) { - switch (entry.Key) - { - case "toc": - return ReadChildren(reader, entry.Entry, null, 0); - } + if (entry.Key == key) + return ReadChildren(key, reader, entry.Entry, null, 0); } } catch (Exception e) @@ -54,7 +57,8 @@ private IReadOnlyCollection Deserialize() return []; } - private IReadOnlyCollection ReadChildren(YamlStreamReader reader, KeyValuePair entry, string? parent, int depth) + private IReadOnlyCollection ReadChildren(string key, YamlStreamReader reader, KeyValuePair entry, string? parent, + int depth) { var entries = new List(); if (entry.Key is not YamlScalarNode { Value: not null } scalarKey) @@ -71,7 +75,11 @@ private IReadOnlyCollection ReadChildren(YamlStreamReader reader, foreach (var tocEntry in sequence.Children.OfType()) { - var child = ReadChild(reader, tocEntry, parent, depth); + + var child = + key == "toc" + ? ReadTocDefinition(reader, tocEntry, parent, depth) + : ReadPhantomDefinition(reader, tocEntry); if (child is not null) entries.Add(child); } @@ -79,7 +87,27 @@ private IReadOnlyCollection ReadChildren(YamlStreamReader reader, return entries; } - private TocReference? ReadChild(YamlStreamReader reader, YamlMappingNode tocEntry, string? parent, int depth) + private TocReference? ReadPhantomDefinition(YamlStreamReader reader, YamlMappingNode tocEntry) + { + foreach (var entry in tocEntry.Children) + { + var key = ((YamlScalarNode)entry.Key).Value; + switch (key) + { + case "toc": + var source = reader.ReadString(entry); + if (source != null && !source.Contains("://")) + source = ContentSourceMoniker.CreateString(NarrativeRepository.RepositoryName, source); + var sourceUri = new Uri(source!); + var tocReference = new TocReference(sourceUri, this, "", true, []); + return tocReference; + } + } + + return null; + } + + private TocReference? ReadTocDefinition(YamlStreamReader reader, YamlMappingNode tocEntry, string? parent, int depth) { string? repository = null; string? source = null; @@ -139,9 +167,6 @@ private IReadOnlyCollection ReadChildren(YamlStreamReader reader, } var navigationItems = new List(); - //TODO not needed - //var tocChildren = mapping.TableOfContentsConfiguration.TableOfContents; - //navigationItems.AddRange(tocChildren); foreach (var entry in tocEntry.Children) { @@ -155,7 +180,7 @@ private IReadOnlyCollection ReadChildren(YamlStreamReader reader, continue; } - var children = ReadChildren(reader, entry, parent, depth + 1); + var children = ReadChildren("toc", reader, entry, parent, depth + 1); navigationItems.AddRange(children); break; } @@ -166,4 +191,5 @@ private IReadOnlyCollection ReadChildren(YamlStreamReader reader, var tocReference = new TocReference(sourceUri, mapping.TableOfContentsConfiguration, path, true, navigationItems); return tocReference; } + } diff --git a/src/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs b/src/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs index ef3f945a7..f591e51bb 100644 --- a/src/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs +++ b/src/docs-assembler/Navigation/GlobalNavigationHtmlWriter.cs @@ -3,53 +3,50 @@ // See the LICENSE file in the project root for more information using System.Collections.Concurrent; +using System.Collections.Immutable; using Elastic.Markdown.IO.Configuration; using Elastic.Markdown.IO.Navigation; using Elastic.Markdown.Slices; namespace Documentation.Assembler.Navigation; -public class GlobalNavigationHtmlWriter(AssembleContext assembleContext, GlobalNavigation navigation, AssembleSources assembleSources) : INavigationHtmlWriter +public class GlobalNavigationHtmlWriter( + GlobalNavigationFile navigationFile, + AssembleContext assembleContext, + GlobalNavigation globalNavigation, + AssembleSources assembleSources) : INavigationHtmlWriter { private readonly AssembleContext _assembleContext = assembleContext; private readonly ConcurrentDictionary _renderedNavigationCache = []; - private (DocumentationGroup, Uri) GetRealNavigationRoot(INavigation navigation) - { - if (navigation is not DocumentationGroup group) - throw new InvalidOperationException($"Expected a {nameof(DocumentationGroup)}"); + private ImmutableHashSet Phantoms { get; } = [.. navigationFile.Phantoms.Select(p => p.Source)]; - - if (group.NavigationRoot is TableOfContentsTree tree) + private (DocumentationGroup, Uri) GetRealNavigationRoot(TableOfContentsTree tree) + { + if (!assembleSources.TocTopLevelMappings.TryGetValue(tree.Source, out var topLevelUri)) { - if (!assembleSources.TocTopLevelMappings.TryGetValue(tree.Source, out var topLevelUri)) - { - _assembleContext.Collector.EmitWarning(_assembleContext.NavigationPath.FullName, $"Could not find a top level mapping for {tree.Source}"); - return (tree, tree.Source); - } - - if (!assembleSources.TreeCollector.TryGetTableOfContentsTree(topLevelUri.TopLevelSource, out var topLevel)) - { - _assembleContext.Collector.EmitWarning(_assembleContext.NavigationPath.FullName, $"Could not find a toc tree for {topLevelUri.TopLevelSource}"); - return (tree, tree.Source); - - } - return (topLevel, topLevelUri.TopLevelSource); - + _assembleContext.Collector.EmitWarning(_assembleContext.NavigationPath.FullName, $"Could not find a top level mapping for {tree.Source}"); + return (tree, tree.Source); } - else if (group.NavigationRoot is DocumentationGroup) + + if (!assembleSources.TreeCollector.TryGetTableOfContentsTree(topLevelUri.TopLevelSource, out var topLevel)) { - var source = group.FolderName == "reference/index.md" - ? new Uri("docs-content://reference/") - : throw new InvalidOperationException($"{group.FolderName} is not a valid navigation root"); - return (group, source); + _assembleContext.Collector.EmitWarning(_assembleContext.NavigationPath.FullName, $"Could not find a toc tree for {topLevelUri.TopLevelSource}"); + return (tree, tree.Source); + } - throw new InvalidOperationException($"Unknown navigation root {group.NavigationRoot}"); + return (topLevel, topLevelUri.TopLevelSource); } public async Task RenderNavigation(INavigation currentRootNavigation, Cancel ctx = default) { - var (navigation, source) = GetRealNavigationRoot(currentRootNavigation); + if (currentRootNavigation is not TableOfContentsTree tree) + throw new InvalidOperationException($"Expected a {nameof(DocumentationGroup)}"); + + if (Phantoms.Contains(tree.Source)) + return string.Empty; + + var (navigation, source) = GetRealNavigationRoot(tree); if (_renderedNavigationCache.TryGetValue(source, out var value)) return value; @@ -64,17 +61,13 @@ public async Task RenderNavigation(INavigation currentRootNavigation, Ca var model = CreateNavigationModel(navigation); value = await ((INavigationHtmlWriter)this).Render(model, ctx); _renderedNavigationCache[source] = value; - if (source == new Uri("docs-content://extend")) - { - } - return value; } private NavigationViewModel CreateNavigationModel(DocumentationGroup group) { - var topLevelItems = navigation.TopLevelItems; + var topLevelItems = globalNavigation.TopLevelItems; return new NavigationViewModel { Title = group.Index?.NavigationTitle ?? "Docs", diff --git a/src/docs-assembler/Navigation/GlobalNavigationPathProvider.cs b/src/docs-assembler/Navigation/GlobalNavigationPathProvider.cs index 91af1c64b..c9e2db754 100644 --- a/src/docs-assembler/Navigation/GlobalNavigationPathProvider.cs +++ b/src/docs-assembler/Navigation/GlobalNavigationPathProvider.cs @@ -2,20 +2,12 @@ // Elasticsearch B.V licenses this file to you under the Apache 2.0 License. // See the LICENSE file in the project root for more information -using System.Collections.Frozen; using System.Collections.Immutable; -using System.Diagnostics.CodeAnalysis; using System.IO.Abstractions; -using Documentation.Assembler.Building; -using Documentation.Assembler.Configuration; -using Documentation.Assembler.Sourcing; using Elastic.Markdown; -using Elastic.Markdown.CrossLinks; using Elastic.Markdown.Diagnostics; using Elastic.Markdown.IO; using Elastic.Markdown.IO.Configuration; -using Elastic.Markdown.IO.Navigation; -using Microsoft.Extensions.Logging.Abstractions; namespace Documentation.Assembler.Navigation; @@ -25,8 +17,9 @@ public record GlobalNavigationPathProvider : IDocumentationFileOutputProvider private readonly AssembleContext _context; private ImmutableSortedSet TableOfContentsPrefixes { get; } + private ImmutableSortedSet PhantomPrefixes { get; } - public GlobalNavigationPathProvider(AssembleSources assembleSources, AssembleContext context) + public GlobalNavigationPathProvider(GlobalNavigationFile navigationFile, AssembleSources assembleSources, AssembleContext context) { _assembleSources = assembleSources; _context = context; @@ -36,45 +29,14 @@ public GlobalNavigationPathProvider(AssembleSources assembleSources, AssembleCon .Select(v => v.Source.ToString()) .OrderByDescending(v => v.Length) ]; - } - - /* - public IFileInfo? LocateDocSetYaml(Uri crossLinkUri) - { - if (!TryGetCheckout(crossLinkUri, out var checkout)) - return null; - - var tocDirectory = _readFs.DirectoryInfo.New(Path.Combine(checkout.Directory.FullName, crossLinkUri.Host, crossLinkUri.AbsolutePath.TrimStart('/'))); - if (!tocDirectory.Exists) - { - _context.Collector.EmitError(_context.NavigationPath, $"Unable to find toc directory: {tocDirectory.FullName}"); - return null; - } - - var docsetYaml = _readFs.FileInfo.New(Path.Combine(tocDirectory.FullName, "docset.yml")); - var tocYaml = _readFs.FileInfo.New(Path.Combine(tocDirectory.FullName, "toc.yml")); - if (!docsetYaml.Exists && !tocYaml.Exists) - { - _context.Collector.EmitError(_context.NavigationPath, $"Unable to find docset.yml or toc.yml in: {tocDirectory.FullName}"); - return null; - } - return docsetYaml.Exists ? docsetYaml : tocYaml; + PhantomPrefixes = [..navigationFile.Phantoms + .Select(p => p.Source.ToString()) + .OrderByDescending(v => v.Length) + .ToArray() + ]; } - public bool TryGetCheckout(Uri crossLinkUri, [NotNullWhen(true)] out Checkout? checkout) - { - if (_checkoutsLookup.TryGetValue(crossLinkUri.Scheme, out checkout)) - return true; - - _context.Collector.EmitError(_context.ConfigurationPath, - !_repoConfigLookup.TryGetValue(crossLinkUri.Scheme, out _) - ? $"Repository: '{crossLinkUri.Scheme}' is not defined in assembler.yml" - : $"Unable to find checkout for repository: {crossLinkUri.Scheme}" - ); - return false; - }*/ - public IFileInfo? OutputFile(DocumentationSet documentationSet, IFileInfo defaultOutputFile, string relativePath) { if (relativePath.StartsWith("_static/", StringComparison.Ordinal)) @@ -124,6 +86,12 @@ public bool TryGetCheckout(Uri crossLinkUri, [NotNullWhen(true)] out Checkout? c if (relativePath.EndsWith(".asciidoc", StringComparison.Ordinal)) return null; + foreach (var prefix in PhantomPrefixes) + { + if (lookup.StartsWith(prefix, StringComparison.Ordinal)) + return null; + } + var fallBack = fs.Path.Combine(outputDirectory.FullName, "_failed", repositoryName, relativePath); _context.Collector.EmitError(_context.NavigationPath, $"No toc for output path: '{lookup}' falling back to: '{fallBack}'"); return fs.FileInfo.New(fallBack); diff --git a/src/docs-assembler/navigation.yml b/src/docs-assembler/navigation.yml index b774fbd24..d286c064e 100644 --- a/src/docs-assembler/navigation.yml +++ b/src/docs-assembler/navigation.yml @@ -6,6 +6,11 @@ # 📝 = no PR started yet ############################################# +# Use sparingly, makes assembler aware of toc container folders +# That are not linked in the global toc but all the children toc they define are. +phantoms: + - toc: elasticsearch://reference + toc: ############# # NARRATIVE #