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

[Request] Stable Builds of DocC Archive #334

Open
AnthonyMDev opened this issue Jul 12, 2022 · 4 comments · May be fixed by #158
Open

[Request] Stable Builds of DocC Archive #334

AnthonyMDev opened this issue Jul 12, 2022 · 4 comments · May be fixed by #158
Assignees
@ethan-kusters

Comments

@AnthonyMDev
Copy link

AnthonyMDev commented Jul 12, 2022 •
edited

Feature Name

Stable Builds of DocC Archive

Description

Creating a .doccarchive is not stable. It results in a different archive each time I build, even if being built from the exact same input. The .doccarchive should be built in a stable method, only changing where modifications to the documentation have occured.

Motivation

Instability in the .doccarchive causes a number of issues for source control and CI/CD pipelines.

  • When checking the .doccarchive into source control, there is a large diff each time it is regenerated. This makes code review difficult and it's unclear if anything has changed at all in the documentation.
  • CI/CD pipelines that deploy the .doccarchive to a server for web hosting are unable to know if there are changes to the archive that need to be redeployed. This requires the documentation to be redeployed every time the .doccarchive is re-compiled.
@franklinsch
Copy link
Member

Thanks for filing @AnthonyMDev! @ethan-kusters I believe you're working on this in #158? Is this still work you're planning to pursue?

@ethan-kusters ethan-kusters self-assigned this Jul 12, 2022
@ethan-kusters
Copy link
Contributor

I am! Currently we're still seeing a slight performance hit when enabling this that I'd like to resolve before landing that PR.

@ethan-kusters ethan-kusters linked a pull request Jul 12, 2022 that will close this issue
Encode JSON with sorted keys by default #158
Draft
3 tasks
@ethan-kusters
Copy link
Contributor

ethan-kusters commented Jul 12, 2022 •
edited

@AnthonyMDev as a workaround until this lands, you should be able to get generally stable builds by enabling this environment variable:

export DOCC_JSON_PRETTYPRINT="YES"

You can see an example of that in the script the Swift-DocC Plugin uses for its documentation site:

https://github.com/apple/swift-docc-plugin/blob/8aca5c5/bin/update-gh-pages-documentation-site#L36

@AnthonyMDev
Copy link
Author

Thank you for that! This definitely helps a ton! Looks like there might be some small bugs, because a couple of my files are getting lines reordered in the json when re-compiled, but it's only a few!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ethan-kusters ethan-kusters

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Encode JSON with sorted keys by default ethan-kusters/swift-docc
3 participants
@AnthonyMDev @ethan-kusters @franklinsch