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] Delete embedded documentation in favor of docs/ #25096

Merged

Conversation

ras0219-msft
Copy link
Contributor

After discussion, we've determined that maintaining the documentation inside the port where fixing typos requires republishing the port, is problematic.

This PR performs one final regenerate run (including the missing port helpers vcpkg-qmake and vcpkg-get-python-modules) and then purges all embedded documentation in the script helpers and port helpers.

This PR does not touch any of the content of this documentation -- that will be done in follow-up PRs.

Drive-by for the helper ports:

  1. "documentation": "https://vcpkg.io/en/docs/README.html"
  2. "license": "MIT"
  3. Use include_guard(GLOBAL) in all script files
  4. Make sure any persistent variables are saved to the cache

Drive-by for the helper ports:
1. "documentation": "https://vcpkg.io/en/docs/README.html"
2. "license": "MIT"
3. Use `include_guard(GLOBAL)` in all script files
4. Make sure any persistent variables are saved to the cache
@Neumann-A
Copy link
Contributor

strictly speaking you cannot have the docs of scripts ports in docs/ since the docs probably depend on the version which gets installed.

@ras0219-msft
Copy link
Contributor Author

We did discuss that as well (it was one of my concerns).

Our approach moving forward will be to include "Added in version x-y-z" annotations where appropriate in future documentation changes. We won't be "backdating" any existing documentation.

@BillyONeal
Copy link
Member

Rather than adding an empty regenerate.ps1 can you just delete this block that was calling it?

# Note that we run docs checks before PR checks because they are likely to invalidate a whole run anyway
- task: Powershell@2
displayName: 'Generate Documentation'
condition: eq('${{ parameters.triplet }}', '${{ variables.ExtraChecksTriplet }}')
inputs:
filePath: 'docs/regenerate.ps1'
arguments: '-VcpkgRoot . -WarningAction Stop'
pwsh: true

@JackBoosY JackBoosY added category:documentation To resolve the issue, documentation will need to be updated info:internal This PR or Issue was filed by the vcpkg team. labels Jun 7, 2022
@ras0219-msft ras0219-msft marked this pull request as ready for review June 7, 2022 21:26
@ras0219-msft
Copy link
Contributor Author

I'm going to go ahead and merge since the previous c645bad passed.

@ras0219-msft ras0219-msft merged commit 7d2449c into microsoft:master Jun 7, 2022
@ras0219-msft ras0219-msft deleted the dev/roschuma/docs-outline branch June 7, 2022 23:26
@dg0yt
Copy link
Contributor

dg0yt commented Jun 8, 2022

From draft to world rebuild in less than 24 hours... But I'm glad this documentation update barrier is removed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
category:documentation To resolve the issue, documentation will need to be updated info:internal This PR or Issue was filed by the vcpkg team.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants