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.

Sign up for GitHub

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

Jump to bottom

[Documentation] A website with Detailed Documentation #1921

Closed
moha-b opened this issue Aug 4, 2023 · 6 comments · Fixed by #1957
Closed

[Documentation] A website with Detailed Documentation #1921

moha-b opened this issue Aug 4, 2023 · 6 comments · Fixed by #1957
Labels
e: documentation Improvements or additions to documentation e: good for newcomers Good for newcomers e: PR welcomed s: best practise It's the best way to do something so far s: feature This issue indicates a feature request

Comments

@moha-b
Copy link

moha-b commented Aug 4, 2023 •
edited
Loading

Request Statement

Kindly provide a full Dio documentation page with simple explanations, usage examples, and API references. Dio's acceptance and popularity in the community will be powered by a user-friendly interface that will make it easy for developers to obtain the required information.

Solution Brainstorm

No response
@moha-b moha-b added the s: feature This issue indicates a feature request label Aug 4, 2023
@AlexV525
Copy link
Member

AlexV525 commented Aug 4, 2023

https://pub.dev/documentation/dio/latest/ should be enough?

@moha-b
Copy link
Author

moha-b commented Aug 5, 2023

Well, having enough is a good starting point, but let's take to the next level. Picture a complete website contains abundance of examples and explanations like how to use dio how to use it with dio cookies and stuff like that it will cater to various skill levels, ensuring everyone can grasp the concepts easily.

@AlexV525 AlexV525 added e: documentation Improvements or additions to documentation e: good for newcomers Good for newcomers s: best practise It's the best way to do something so far e: PR welcomed labels Aug 5, 2023
@AlexV525
Copy link
Member

AlexV525 commented Aug 5, 2023

The idea is good, though we don't have enough resources to implement such improvements. Any PRs are welcome for the idea.

@ueman
Copy link
Contributor

ueman commented Aug 18, 2023 •
edited
Loading

According to dartdocs documentation, we can include Markdown files in the generated docs. See https://pub.dev/packages/dartdoc#advanced-features. I guess that would be a good starting point.
That would make it easy to add, easy to maintain, and we don't have to host an extra webpage.

Edit: I played around with this, but it doesn't actually works the way I imagined.
Edit 2: I've been told that it should work. I'll try to look into this once again.

Edit3: go router does it. See for example https://pub.dev/documentation/go_router/latest/topics/Get%20started-topic.html

@ueman ueman mentioned this issue Sep 8, 2023
Merged
7 tasks
@ueman
Copy link
Contributor

ueman commented Sep 14, 2023

@moha-b Feel free to add and improve the documentation after #1957 lands.

It might not be as good as others, but it's a start.

@moha-b
Copy link
Author

moha-b commented Sep 14, 2023

I guess it will be great it's an amazing effort from you @ueman 🙏

github-merge-queue bot pushed a commit that referenced this issue Sep 18, 2023
@ueman
Improved documentation (#1957)
a20f635 
This adds doc pages to the existing API docs. This is similar to the
approach of the docs of GoRouter, see for example the following page:
https://pub.dev/documentation/go_router/latest/topics/Get%20started-topic.html

This works by making use of categories (also called topics). See dartdoc
explanation at https://pub.dev/packages/dartdoc#advanced-features

### How to test this

Execute `dart doc` in the dio folder. This creates the docs. When
opening the index.html, you should see the newly added migration page in
the API docs.

### Further stops

I'll try to migrate further documentation to, but further I'd like some
feedback.

### New Pull Request Checklist

- [x] I have read the
[Documentation](https://pub.dev/documentation/dio/latest/)
- [x] I have searched for a similar pull request in the
[project](https://github.com/cfug/dio/pulls) and found none
- [x] I have updated this branch with the latest `main` branch to avoid
conflicts (via merge from master or rebase)
- [ ] I have added the required tests to prove the fix/feature I'm
adding
- [x] I have updated the documentation (if necessary)
- [x] I have run the tests without failures
- [ ] I have updated the `CHANGELOG.md` in the corresponding package

### Additional context and info (if any)

<!-- Provide more context and info about the PR. -->

Fixes #1921
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
e: documentation Improvements or additions to documentation e: good for newcomers Good for newcomers e: PR welcomed s: best practise It's the best way to do something so far s: feature This issue indicates a feature request
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Improved documentation cfug/dio
3 participants
@ueman @AlexV525 @moha-b