Make documentation more verbose

[Charlton-A]

I've been tinkering with the framework, and while the learning curve has been minimal, one challenge I've faced is that the documentation is less verbose. However, this can be supplemented by looking at the implementation and tests to understand how to implement certain features.

For example, when testing routes with paths, my initial approach was to use f-strings to build the URL, but that didn't work. After checking out the Emmett test for auth https://github.com/emmett-framework/emmett/blob/master/tests/test_auth.py#L213, I followed the same approach shown there, which solved the issue.

Would it be a good idea to make the documentation a bit more versbose? Perhaps creating a 'testing-how-to.md' or 'orm-how-to-md' that includes snippets for implementing key features and highlights certain gotchas would be helpful. For instance, in the ORM, it's easy to assume that update and update_record are the same due to muscle memory from other ORMs. A quick reference guide like this could be useful for new developers.

[gi0baro]

Would it be a good idea to make the documentation a bit more versbose? Perhaps creating a 'testing-how-to.md' or 'orm-how-to-md' that includes snippets for implementing key features and highlights certain gotchas would be helpful.

Love the idea. Like a grab 'n go section per chapter.

After checking out the Emmett test for auth https://github.com/emmett-framework/emmett/blob/master/tests/test_auth.py#L213, I followed the same approach shown there, which solved the issue.

That sounds strange though, as there should be no difference between f"{whatever}" and "{}".format(whatever). Are you sure that was the actual issue? On the documentation topic I would rather add in the docs the ability to use url() when using the test client, for instance.

For instance, in the ORM, it's easy to assume that update and update_record are the same due to muscle memory from other ORMs. A quick reference guide like this could be useful for new developers.

I totally agree. To give you more context, whereas I'm generally happy on how docs looks today, I'd say there are 2 major things to consider with the documentation in Emmett:

• the whole documentation was written by me – with the majority of it being untouched in years – which means the general point of view is definitely biased towards also being the author;
• the time factor: the number of projects I maintain grew in the years, and given in most of the cases I'm the sole maintainer the available time has to be split also between coding, issues, community, etc., leaving generally just a tiny amount for docs – for instance, whereas the whole HTML generation code was there since 0.1, the actual docs chapter was written for the 2.6 release O.o

So if you could make few contributions on that side it would be tremendously helpful: even just for the "fresh point of view" compared to mine.
And I'm not asking for you to actually write documentation: if you can just capture, as a new developer, all the specific points you found out the documentation was not detailed enough – or completely missing – then I can use that list/notes to improve the docs in this sense :)

[Charlton-A]

I have tested both f"{whatever}" and "{}".format(whatever) for the route issue, and both worked as expected. I wasn't able to replicate the problem, so I believe it might have been related to how I defined the route. If the issue arises again, I'll create an issue to track it.

Regarding the documentation, I understand that you're maintaining several projects, and you might not have enough time to focus more on docs. I came across Emmett while researching Granian. I'd be happy to note specific points that could be suitable for a grab 'n go section. I also don't mind drafting the documentation once it's approved.

For example:

• Emmett Auth: It can be extended and isn't highly opinionated. It was easy for me to create basic authentication without requiring the full module. I quickly wrapped a Bootstrap template around it and only had to extend the AuthUserBasic model a bit . New users might benefit from knowing they're not strictly limited to using the default authentication system.
• Emmett Auth: When creating relationships for User(AuthUser) example refers_to("plan") . When initializing the Auth module , Plan should registered before auth is initialized with User model .

db = Database(app)
db.define_models(Plan)
auth = Auth(app, db, user_model=User)