Issue 1759 documentation

[bikash119]

This PR closes #1759

[r4victor]

I think the instructions on how to build the docs should be added to DEVELOPMENT.md since DOCUMENTATION.md as of now duplicates it a lot. Also, we do not include dev dependencies in setup.py's [all]. Better to simply list them in requirements_docs.txt. The exact deps can be found in the docs.yaml github action:

https://github.com/dstackai/dstack/blob/55d09a7cfe5ddff7f95ddd5f02afbb92662bd36b/.github/workflows/docs.yaml#L26-L31

[bikash119]

Thank you @r4victor for reviewing the work. Will incorporate the feedback.

[bikash119]

@r4victor : I have incorporated the feedback suggested.

[r4victor]

The deps list is missing pillow and cairosvg. Also, there should be an instruction for installing system deps on Linux/macOS.

I think It's more flexible to put docs deps in requirements_docs.txt so that the contributors don't need to install them if they are not working on docs.

[SamirPS]

Why not using poetry instead of requirement.txt?

[peterschmidt85]

@bikash119 I'm sorry but I don't see much value in this PR. The issue is important. Indeed it's unclear how to contribute to the docs and test the results. However, this PR doesn't help much. Also, there is an issue. dstack uses MKDocs Insiders which requires GitHub token to install MKDocs Insiders. We cannot share our token. But still some guidance might be helpful I suppose. Currently, it's unclear for an external contributor how to contribute to the docs - regardless whether the user has or doesn't have a MKDocs Insiders token.

[bikash119]

Thank you for your comments @peterschmidt85 . Based on comments from @r4victor , I think a external contributor can comment out the insider plugin in their local dev environment. As of today, its takes a little of debugging to get the mkdocs build to work. If we incorporate the feedbacks from @r4victor , external contributors can add documentations. The CI workflow may be tweaked to verify if insider plugin is enabled for the build in PR request. Please let me know if this sounds good. I will incorporate the feedbacks from @r4victor

[peterschmidt85]

@bikash119 Basically we could add DOCUMENTATION.md under contributing and include clear instructions there on how to work with documentations - including how to set up the environment and test it.

[bikash119]

@peterschmidt85 : In my first PR I had the exact same approach of adding DOCUMENTATION.md to contributing. After review comments from @r4victor which I agree as a it was duplication of DEVELOPMENT.md.

[peterschmidt85]

@bikash119 We've just discussed it with @r4victor and agreed on the following:

1. We don't change setup.py or requirements_dev.txt
2. Instead, we introduce contributing/DOCUMENTATION.md but we have there two sections: 2.1. Development setup (should mention that how to set up both with and without insider plugin) 2.2. Working on the documentation (or something like that) that would elaborate a bit on how documentation is organized, how to test it locally, including how examples are organized (and when and how they are copied). Additionally, there should be a minimal section on the style but feel free to keep it blank – i can help with that.

[bikash119]

Thank you @peterschmidt85 for detailed notes. Will work on it right now.

[bikash119]

@bikash119 We've just discussed it with @r4victor and agreed on the following:

1. We don't change `setup.py` or `requirements_dev.txt`

2. Instead, we introduce `contributing/DOCUMENTATION.md` but we have there two sections:
   2.1. `Development setup` (should mention that how to set up both with and without insider plugin)
   2.2. `Working on the documentation` (or something like that) that would elaborate a bit on how documentation is organized, how to test it locally, including how examples are organized (and when and how they are copied). Additionally, there should be a minimal section on the style but feel free to keep it blank – i can help with that.

Here are my changes:

• Kept the documentation dependencies in requirements_dev.txt. One of the feedback from @r4victor is to have different requirements_doc.txt for doc dependencies. May be we should keep it in requirements_dev.txt as most of the code changes will need some addition/ deletion to documentation. Please let me know if you think otherwise. Will create a new requirements_doc.txt
• Created DOCUMENTATION.md which includes the steps for both development setup and documentation setup.
• Deleted DEVELOPMENT.md

[peterschmidt85]

@bikash119 You changed requirements_dev.txt and setup.py. It goes against what we agreed. Also, you simply copied Development setup instructions from DEVELOPMENT.md to DOCUMENTATION.md instead what we agreed upon above. This doesn't make sense to me.

[bikash119]

My bad @peterschmidt85 . Let me rework on it.

[bikash119]

@peterschmidt85 , since this branch was messed up because of deletions and additions of new files. I have created a new PR : https://github.com/dstackai/dstack/pull/1848.

[github-actions[bot]]

This PR is stale because it has been open for 14 days with no activity.

[github-actions[bot]]

This PR was closed because it has been inactive for 7 days since being marked as stale. Please reopen the PR if it is still relevant.