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

Enable Overview, Installation & Configuration pages to be stored inside the repository #224

Closed
3 of 4 tasks
Tracked by #222
infin8x opened this issue Oct 19, 2021 · 4 comments
Closed
3 of 4 tasks
Tracked by #222
Assignees
Labels
kind/enhancement Improvements or new features resolution/fixed This issue was fixed

Comments

@infin8x
Copy link
Contributor

infin8x commented Oct 19, 2021

Hello!

  • Vote on this issue by adding a 👍 reaction
  • If you want to implement this feature, comment to let us know (we'll work with you on design, scheduling, etc.)

Issue details

Today, hand-authored Overview and Installation & Configuration pages for a Pulumi Package are stored in https://github.com/pulumi/registry. As part of #222 and in preparation for #206, we should:

  • Enable the package publish process to pull the Overview content directly from the package's README
  • Ensure the boilerplate repositories provide a great README template such that the package will look great in Pulumi Registry
  • Enable the package publish process to pull the Installation & Configuration content from docs/installation-configuration.md
  • Update Pulumi Registry to hide the Installation & Configuration tab if docs/installation-configuration.md is blank
@infin8x infin8x added the kind/enhancement Improvements or new features label Oct 19, 2021
@jkodroff
Copy link
Member

jkodroff commented Jun 5, 2023

Suggested change from Alex's design above:

I think the provider repo README and Registry installation and configuration page serve different purposes: The repo README should center around developers working on the provider code itself. The installation and configuration doc is for end users trying to use the provider.

Now that we have the Registry, the Registry is the primary entrypoint for users of a provider and I don't expect that most folks visiting the GH repo for the provider are looking for end-user information, so I suggest that we:

  1. Keep all end-user documentation (i.e., installation and configuration) in a known file location in the provider repo, e.g. docs/installation_and_configuration.md.
  2. Refer readers of the provider's README to the installation and configuration file for details
  3. Change the registry to pull from the provider repo for installation and configuration content before checking in the registry repo.

The Snowflake registry page refers users to the provider repo README for the full list of config options, and I think that we want to center the registry in the user experience rather than directing them elsewhere.

@github-project-automation github-project-automation bot moved this to 🤔 Triage in Docs 📚 Apr 25, 2024
@sean1588 sean1588 removed this from Docs 📚 Apr 25, 2024
@github-project-automation github-project-automation bot moved this to 🤔 Triage in Docs 📚 Apr 25, 2024
@sean1588 sean1588 moved this from 🤔 Triage to 🧳 Backlog in Docs 📚 Apr 25, 2024
@iwahbe iwahbe added the resolution/fixed This issue was fixed label Nov 6, 2024
@iwahbe
Copy link
Member

iwahbe commented Nov 6, 2024

This is already possible today, docs/_index.md in the source repo is the overview page. docs/installation-configuration.md is the installation page.

@iwahbe iwahbe closed this as completed Nov 6, 2024
@github-project-automation github-project-automation bot moved this from 🧳 Backlog to 🏁 Done in Docs 📚 Nov 6, 2024
@pulumi-bot
Copy link
Collaborator

Cannot close issue:

  • does not have an assignee

Please fix these problems and try again.

@iwahbe
Copy link
Member

iwahbe commented Nov 6, 2024

I have opened follow-up issues in each of our boilerplate repos.

@iwahbe iwahbe closed this as completed Nov 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind/enhancement Improvements or new features resolution/fixed This issue was fixed
Projects
Status: 🏁 Done
Development

No branches or pull requests

5 participants