search

daytonaio / docs

Official Documentation for Daytona
https://daytona.io/docs
Apache License 2.0
2 stars 2 forks source link

Automate CLI reference generation #40

Closed osslate closed 1 month ago

osslate commented 1 month ago

Closes #22.

This PR adds a CLI reference generation script based on the export from Cobra. The CLI reference for 0.16.x looks like this:

image

Areas of future improvement

Tpuljak commented 1 month ago

OO until Monday but just wanted to mention that the MD files won't live on download.daytona.io. They should only be fetched from Daytona's Github. If you need directory listing, you can use Github's API.

I can help you out with that on Monday.

osslate commented 1 month ago

@Tpuljak sounds good, I'll look into it more in the meantime.

osslate commented 1 month ago

The workflow thought of here is, once a new Daytona release is tagged --- and before the corresponding docs release goes out:

  1. I run the script locally to generate docs for the newly tagged Daytona release
  2. I verify the contents, commit and push the new autogenerated doc

So this is essentially the last step on my end before a new docs release is tagged and pushed to prod. I'm fine leaving it in ./tools as it's directly related to the docs publication process, and it also caters for customizing the Markdown before/after the autogenerated stuff (which we'll use later).

There might be a way to automate it in the future, but we don't need to worry about it for now.

Tpuljak commented 1 month ago

There might be a way to automate it in the future, but we don't need to worry about it for now.

Okay, let's leave it for now but I would def recommend we automate this because it seems very "automatable" if that makes sense 😄

osslate commented 1 month ago

  1. inconsistent "option" markdown, some are code some are bash. not sure which is best @Tpuljak can weigh in

    1. Missing overview text

    2. Not sure if these are useful; daytona Daytona is a Dev Environment Manager

Synopsis Daytona is a Dev Environment Manager

  1. I can see this now, will fix
  2. Will add that back
  3. The daytona command does something, even if the autogenerated docs aren't useful in it's current form. Since these are generated based on docs living in @daytonaio/daytona, I'll also start sending PRs there to make the CLI docs more useful, and gradually, the docs published here will follow.

I'll open an issue over in @daytonaio/daytona to update these docs for now. In the future, updates to the autogenerated CLI reference should probably go over to @daytonaio/daytona as that's where they live, but opening up to @Tpuljak @idagelic for feedback

idagelic commented 1 month ago

I'll open an issue over in @daytonaio/daytona to update these docs for now. In the future, updates to the autogenerated CLI reference should probably go over to @daytonaio/daytona as that's where they live, but opening up to @Tpuljak @idagelic for feedback

That is correct - anything that gets "autogenerated" comes from the main repo and all the descriptions of commands/flags etc. may be changed so if you've got recommendations, just open up an issue.

osslate commented 1 month ago

@ivan-burazin fixed the first 2 issues

osslate commented 1 month ago
  1. daytona - Daytona is a Dev Environment Manager. true daytona is a command as such there should be text ecpain what it does, this is just the title

I agree it needs to be updated. As mentioned in https://github.com/daytonaio/docs/pull/40#issuecomment-2145577937 and https://github.com/daytonaio/docs/pull/40#issuecomment-2145600838, the generated documentation comes directly from Daytona's CLI. In order to update that, we need to submit a PR to the Daytona repo. Whatever you get with daytona --help commands is what becomes the docs here.

I'll open a PR to improve the CLI docs, but it won't filter down to the docs site until they're accepted there by Toma/Ivan/Luka and until they become part of a new Daytona release.

  1. Synopsis Daytona is a Dev Environment Manager. what is Synopsis what does this mean?

I believe the "Synposis" part is generated from one of the "Short" or "Long" descriptions defined here. https://github.com/daytonaio/daytona/blob/main/pkg/cmd/cmd.go#L26-L32

Maybe @Tpuljak or @idagelic have an idea of why this section is generated.

  1. CLI overview, should be have a bit more fluff. suggest a paragraph for every overview

Is there anything in particular you'd add to the intro? Generally with documentation, the objective is to avoid fluff and focus on getting to the point. I'm not sure what else to add in the intro that's useful for users, but open to suggestions :)

  1. missing core command but has options; daytona container-registry,daytona git-providers...possibly others

Could you clarify? I can see doc entries for both daytona container-registry and daytona git-providers:

image image
idagelic commented 1 month ago

I believe the "Synposis" part is generated from one of the "Short" or "Long" descriptions defined here. https://github.com/daytonaio/daytona/blob/main/pkg/cmd/cmd.go#L26-L32

Maybe @Tpuljak or @idagelic have an idea of why this section is generated.

That is correct - the synopsis part is generated from the "Long" description. In the CLI it appears when you run a specific command's --help. Removing the "long" description also removes the synopsis (as well as the heading). Let me know what you want to have there in an issue on the main repo.

ivan-burazin commented 1 month ago

I believe the "Synposis" part is generated from one of the "Short" or "Long" descriptions defined here. https://github.com/daytonaio/daytona/blob/main/pkg/cmd/cmd.go#L26-L32 Maybe @Tpuljak or @idagelic have an idea of why this section is generated.

That is correct - the synopsis part is generated from the "Long" description. In the CLI it appears when you run a specific command's --help. Removing the "long" description also removes the synopsis (as well as the heading). Let me know what you want to have there in an issue on the main repo.

Its fin that the CLI has this, but it makes no sense in the cli, so would just script it to be removed

ivan-burazin commented 1 month ago

@osslate needs more context, people don't know anything about Daytona when landing here as such it next to convey what this is as much as possible.

missing commands ![Uploading Screenshot 2024-06-04 at 15.53.03.png…]()

ivan-burazin commented 1 month ago

@osslate lmk when to review again.