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.

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

docs: Config reference #3367

Merged
merged 12 commits into from
Mar 24, 2025
Merged

docs: Config reference #3367

merged 12 commits into from
Mar 24, 2025

Conversation

igneus
Copy link
Contributor

@igneus igneus commented Feb 27, 2025

For a start of #2431 here's the Config reference page generated using the approach outlined in the issue description.

Unfortunately the contents generated this way are more confusing than helpful (even the FieldName table cells are often empty, the other contents, if available, are rather enigmatic). And for ZClient.Config attempt to generate the table results in stack overflow.

/claim #2431

@igneus igneus force-pushed the config-reference branch from d802319 to c1eb78b Compare March 2, 2025 02:07
@igneus
Copy link
Contributor Author

igneus commented Mar 2, 2025

ZClient.Config is not included, as an attempt to generate its documentation results in stack overflow (zio/zio-config#1545).

Please note that the output is affected by zio/zio-config#1542 , which is also source of the broken links reported by docusaurus. PR with a fix is linked to the issue.

@igneus igneus marked this pull request as ready for review March 4, 2025 18:37
@987Nabil
Copy link
Contributor

@igneus I just hit publish on zio-config. Can you update it once it is released?

@igneus
Copy link
Contributor Author

igneus commented Mar 17, 2025

@987Nabil Thanks, done.

sbt compileDocs still emits some warnings (caused by this PR), because the generated markdown contains links to anchors which are only created when producing HTML (=> are not available when markdown link targets are being checked). If preferable, this could be fixed by generating our own anchors instead of relying on the auto-generated ones. But I would prefer not to, as it would involve markdown with inline HTML like

# <a name="custom-heading-anchor"></a>Heading Text

and that's rather ugly.

@987Nabil 987Nabil merged commit 8c1f2ff into zio:main Mar 24, 2025
37 checks passed
mhodovaniuk pushed a commit to mhodovaniuk/zio-http that referenced this pull request Mar 28, 2025
* docs: Config reference

* scalafmt

* scalafix

* simplify

* delete entries of configs which only appear nested in others

* make zio-http-gen visible to zio-http-docs

* docs: Config reference: each config on a separate page

because Table.toGithubFlavouredMarkdown() assumes it owns the page and
the anchor IDs clash when multiple configs are dumped on a single page

* website: sidebar: fix document IDs

* docs: Config reference: shorten sidebar labels

* docs: Config reference: introduction page

* Update zio-config to 4.0.4

---------

Co-authored-by: Nabil Abdel-Hafeez <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants