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

Remove docs & improve README #14

Merged
merged 5 commits into from
Dec 27, 2024
Merged

Remove docs & improve README #14

merged 5 commits into from
Dec 27, 2024

Conversation

giograno
Copy link
Member

After an internal discussion (mostly after feedback from @thrau), I decided to drop the sphinx docs and keep all the docs related to the SDK in our official user documentation.

One of the biggest pro of sphinx was the API reference generation from docstrings which we can still re-introduce at some point in the official docs, if we want. I'd argue that the reference becomes less important once we open-source this repo.

In the context of this PR, I also improved our README, with a pointer to the docs for a quickstart and code samples.

@giograno giograno marked this pull request as ready for review December 11, 2024 22:40
Copy link
Member

@alexrashed alexrashed left a comment

Choose a reason for hiding this comment

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

After an internal discussion (mostly after feedback from @thrau), I decided to drop the sphinx docs and keep all the docs related to the SDK in our official user documentation.
One of the biggest pro of sphinx was the API reference generation from docstrings which we can still re-introduce at some point in the official docs, if we want. I'd argue that the reference becomes less important once we open-source this repo.

I think this is a very interesting discussion to have. It's totally fine to take them down for now, but it would be super interesting what the reasoning against publishing their own fine-grained docs is (in the PR description you only mentioned the "pro" of Sphinx).

I found a small issue in the README (wrong badge) which would be good to fix before merging, the rest of my comments really are just nitpicks. These shouldn't be blocking the merge (and are quite subjective I would say).

giograno and others added 4 commits December 12, 2024 14:58
Co-authored-by: Alexander Rashed <[email protected]>
Co-authored-by: Alexander Rashed <[email protected]>
Co-authored-by: Alexander Rashed <[email protected]>
Co-authored-by: Alexander Rashed <[email protected]>
@giograno
Copy link
Member Author

giograno commented Dec 27, 2024

@alexrashed I was convinced by our internal discussion (especially by the comment of @thrau).
I was very attracted by the automatic generation of the API reference from docstrings but:

  • we can still do this in the future in our main docs;
  • getting started guides and code samples are more important for adoptions (and we have these already in the main docs).

@giograno giograno merged commit 74f08bd into main Dec 27, 2024
@giograno giograno deleted the docs branch December 27, 2024 09:12
giograno added a commit that referenced this pull request Jan 27, 2025
giograno added a commit that referenced this pull request Jan 27, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants