Skip to content

Improve docs#2135

Merged
r4victor merged 8 commits intomasterfrom
pr_docs_improvements
Dec 25, 2024
Merged

Improve docs#2135
r4victor merged 8 commits intomasterfrom
pr_docs_improvements

Conversation

@r4victor
Copy link
Copy Markdown
Collaborator

@r4victor r4victor commented Dec 24, 2024 •
edited
Loading

Closes #1603

The PR:

  • Fixes documentation bugs and typos.
  • Expands concepts guides, clarifies Tasks vs Services.
  • Describes Versioning policy.
  • Removes long deprecated fields from reference.
  • Fixes broken links.
  • Builds docs in strict mode.
  • Adds docs build step to Build workflow.
  • Speeds up docs generation from ~15s to ~5s by processing files concurrently.
  • Other minor adjustments.

peterschmidt85
peterschmidt85 reviewed Dec 24, 2024
View reviewed changes
docs/docs/concepts/repos.md
use `--local` with [`dstack init`](../reference/cli/dstack/init.md).

## Override the repo
## Specify the repo
Copy link
Copy Markdown
Contributor

@peterschmidt85 peterschmidt85 Dec 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO the semantics here is a bit unclear

Copy link
Copy Markdown
Contributor

@peterschmidt85 peterschmidt85 Dec 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest "Inline repo initialization" instead of "Specify the repo"

Copy link
Copy Markdown
Collaborator Author

@r4victor r4victor Dec 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The section is less about repo init and more about the possibility to specify repo for dstack apply. I'd not focus on initialization since it's not the user goal. Maybe "Use repos with dstack apply"?

peterschmidt85
peterschmidt85 reviewed Dec 24, 2024
View reviewed changes
peterschmidt85
peterschmidt85 reviewed Dec 24, 2024
View reviewed changes
peterschmidt85
peterschmidt85 reviewed Dec 24, 2024
View reviewed changes
docs/docs/guides/troubleshooting.md Outdated
```

#### Backend configuration
#### Cause 1: Backend configuration
Copy link
Copy Markdown
Contributor

@peterschmidt85 peterschmidt85 Dec 24, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a fan of repeating Cause # multiple times - make reading the document a bit hard

Copy link
Copy Markdown
Collaborator Author

@r4victor r4victor Dec 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It actually looks much better than current headings when rendered. Because currently it's hard to visually differentiate between problems and possible causes/solutions:

Screenshot 2024-12-25 at 10 43 56

peterschmidt85
peterschmidt85 approved these changes Dec 24, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@peterschmidt85 peterschmidt85 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a few comments and made a few minor improvements

jvstme
jvstme approved these changes Dec 25, 2024
View reviewed changes
Copy link
Copy Markdown
Collaborator

@jvstme jvstme left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@r4victor, special thanks for improving the build pipelines. Did you also have a chance to look into these parts of #1603?

  • See if building in strict mode fails when there are broken anchor links. If not, come up with a solution
  • See if there are solutions to check external links when building

r4victor
r4victor commented Dec 25, 2024
View reviewed changes
docs/docs/guides/server-deployment.md
[`~/.dstack/server/config.yml`](../reference/server/config.yml.md#encryption).

## Versioning policy
## Backward compatibility
Copy link
Copy Markdown
Collaborator Author

@r4victor r4victor Dec 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@peterschmidt85, Backward compatibility is only one aspect of the Versioning policy. Versioning/version policy is a standard term:

@r4victor @jvstme
Apply suggestions from code review
e50b64a 
Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>
@r4victor
Copy link
Copy Markdown
Collaborator Author

r4victor commented Dec 25, 2024

@jvstme

See if building in strict mode fails when there are broken anchor links.

There are still broken anchors – these are logged with INFO and does not fail in strict mode. mkdocs allows changing this and fail as well.

See if there are solutions to check external links when building

I haven't researched this.

@r4victor r4victor merged commit cc67a8a into master Dec 25, 2024
@r4victor r4victor deleted the pr_docs_improvements branch December 25, 2024 10:04
pranitnaik43 pushed a commit to bahaal-tech/dstack that referenced this pull request Feb 9, 2025
@r4victor @peterschmidt85 @jvstme
Improve docs (dstackai#2135)
40e778d 
* Improve docs

* Fix broken links

* Build docs in strict mode

* [Docs] Prevent broken links in dstack docs dstackai#1603 (review suggestions)

* Apply suggestions from code review

Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>

* Move retry reference

* Speed up docs generation

* Improve troubleshooting heading

---------

Co-authored-by: peterschmidt85 <andrey.cheptsov@gmail.com>
Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>
pranitnaik43 pushed a commit to bahaal-tech/dstack that referenced this pull request Mar 4, 2025
@r4victor @peterschmidt85
@jvstme @pranitnaik43
Improve docs (dstackai#2135)
d6f3ca8 
* Improve docs

* Fix broken links

* Build docs in strict mode

* [Docs] Prevent broken links in dstack docs dstackai#1603 (review suggestions)

* Apply suggestions from code review

Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>

* Move retry reference

* Speed up docs generation

* Improve troubleshooting heading

---------

Co-authored-by: peterschmidt85 <andrey.cheptsov@gmail.com>
Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>
pranitnaik43 pushed a commit to bahaal-tech/dstack that referenced this pull request Mar 5, 2025
@r4victor @peterschmidt85
@jvstme @pranitnaik43
Improve docs (dstackai#2135)
28a9411 
* Improve docs

* Fix broken links

* Build docs in strict mode

* [Docs] Prevent broken links in dstack docs dstackai#1603 (review suggestions)

* Apply suggestions from code review

Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>

* Move retry reference

* Speed up docs generation

* Improve troubleshooting heading

---------

Co-authored-by: peterschmidt85 <andrey.cheptsov@gmail.com>
Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jvstme jvstme jvstme approved these changes

@peterschmidt85 peterschmidt85 peterschmidt85 approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Prevent broken links in dstack docs

3 participants

@r4victor @jvstme @peterschmidt85