From 43dc492bc4392c49364ad8a99eb8db5c3e4d0b0c Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Wed, 31 May 2023 18:40:00 +0200 Subject: [PATCH] Document URL Reader export-ignore limitations Signed-off-by: Eric Peterson --- docs/features/techdocs/troubleshooting.md | 21 +++++++++++++++++---- docs/plugins/url-reader.md | 10 ++++++++++ 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docs/features/techdocs/troubleshooting.md b/docs/features/techdocs/troubleshooting.md index d8b413be5c..3f0daba101 100644 --- a/docs/features/techdocs/troubleshooting.md +++ b/docs/features/techdocs/troubleshooting.md @@ -5,11 +5,24 @@ sidebar_label: Troubleshooting description: Troubleshooting for TechDocs --- -## Failure to clone +## Documentation not found when generating -TechDocs will fail to clone your docs if you have a git config which overrides -the `https` protocol with `ssh` or something else. Make sure to remove your git -config locally when you try TechDocs. +This may happen if you have TechDocs set up using the "out-of-the-box" +configuration, wherein documentation is built dynamically by the TechDocs +backend, and your TechDocs files are being pulled from a git-based source +control management system (e.g. GitHub, BitBucket, etc). + +If you experience this, check that TechDocs-related files (e.g. markdown, +assets, or the `mkdocs.yml` file) are not matched by an `export-ignore` +attribute in a `.gitattributes` file in the relevant repository. + +TechDocs' backend is not able to see such files, and therefore may generate +partial (or no) TechDocs as a result. + +You'll need to reconsider how you distribute tar archives based on your source +code (and how you prevent internal documentation from being included in those +archives). Alternatively, you could consider switching to the "recommended" +TechDocs architecture (documentation generated and published in CI/CD). ## MkDocs Build Errors diff --git a/docs/plugins/url-reader.md b/docs/plugins/url-reader.md index fa9c341543..c8ff18952c 100644 --- a/docs/plugins/url-reader.md +++ b/docs/plugins/url-reader.md @@ -106,6 +106,16 @@ directly be used with a URL. Some example usages - Catalog using the `search` method to find files for a location URL containing a glob pattern. +Note that URL Readers which target git-based version control systems may, under +the hood, leverage the ability to create tar archives based on a specific git +commit-ish. A consequence of this is that files and directories configured with +[the `export-ignore` attribute](https://git-scm.com/docs/gitattributes#_creating_an_archive) +via `.gitattributes` will not be visible to the URL reader when using the +`readTree` or `search` methods. + +Be aware of this limitation and ensure that end-users of your plugin are also +aware via, for example, documentation. + ## Writing a new URL Reader If the available URL Readers are not sufficient for your use case and you want