Documentation Enhancements

[harshanarayana]

• - Document missing APIs
• - Enhance Example Section in Document
• - Categorize Extensions based on groups (Suggestions on the group order is welcome)
• - Fix minor formatting issues
• - Release manager script with Calendar Verison and Micro release support.
• - Add examples with External monitoring and error reporting service integration. (Sentry, Rollbar, Raygun and Logdna)
• - Release versioning script compliant with Black
• - Minor tweaks to the documentation with formatting and text contents
• - Reordered index in the document to simplify the use for first-time users.
• - Run Tests using setup.py
• - Additional Makefile commands for testing and Coverage Report

Note: There are still a few more sanic classes that need API documentation. I will go ahead and create a different PR for them.

[codecov]

Codecov Report

Merging #1424 into master will increase coverage by 0.05%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master    #1424      +/-   ##
==========================================
+ Coverage   91.26%   91.32%   +0.05%     
==========================================
  Files          17       17              
  Lines        1717     1717              
  Branches      322      322              
==========================================
+ Hits         1567     1568       +1     
  Misses        123      123              
+ Partials       27       26       -1

Impacted Files	Coverage Δ
sanic/router.py	95.89% <ø> (+0.45%)	⬆️
sanic/handlers.py	98.09% <ø> (ø)	⬆️
sanic/exceptions.py	100% <ø> (ø)	⬆️
sanic/cookies.py	100% <ø> (ø)	⬆️
sanic/app.py	91.21% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 67d51f7...9bea23d. Read the comment docs.

[ahopkins]

Nice work.

[harshanarayana]

@ahopkins @vltr @yunstanford I just added a basic Release management script that can automatically manage calendar version with micro-release support and change log generation for release note. I would really appreciate it if you guys could take a look and provide a feedback on that script.

[ahopkins]

Will do. I also want to make some edits to the README, and the intro page. I was thinking I'd do a separate PR, but maybe I will commit to this one.

[harshanarayana]

@ahopkins Great. Let me know if there is something I can add to the README from my side to simplify your work.

[yunstanford]

awesome, thanks!

[vltr]

I don't know if everyone would agree with me, but this could be inside a .ci directory of some kind, specially if ignored by the MANIFEST.in file. Looking at the MANIFEST.in file now, I actually see that we have some work to do in there as well ...

[harshanarayana]

@vltr I like the idea of keeping all CI/CD tools in a common directory so that they are out of the way of regular development.

As for the MANIFEST.in goes, I was thinking of doing it as a different PR. But I can change it as part of this one as well if you want me to.

Just an FYI, check out https://flit.readthedocs.io/en/latest/

[vltr]

@harshanarayana yeah, there are some tools today that can do that for us ... There is towncrier to automate the changelog entries (you can see it in use in the attrs project). There's poetry that can handle some of the same stuff that flit does, but I actually have never used them and, while the eternal discusion over a new tool that "does everything in packaging" isn't over with a consensus, I guess we'll stick to setuptools for a while ...

[harshanarayana]

@vltr towncrier seems interesting. I didn't know about it before you mentioned it here.
I was thinking of making the necessary changes to the MANIFEST.in fie. Do you have any suggestions on what might be good to go there?
I was thinking the following.

1. Documentations (Raw files not the _build)
2. Setup
3. Tests
4. yml, md, rst, license, txt, ini from the base directory.

[harshanarayana]

➜ check-manifest -u -v
listing source files under version control: 185 files and directories
building an sdist: sanic-0.8.3.tar.gz: 185 files and directories
copying source files to a temporary directory
building a clean sdist: sanic-0.8.3.tar.gz: 185 files and directories
lists of files in version control and sdist match

Manifest Coverage after new changes to manifest

[vltr]

Wow! Are you trying to do all the hardwork by yourself? 😅

Indeed, towncrier seems like a nice tool to provide a complete changelog and that kind of stuff, even though I have not used it myself (yet).

As for the MANIFEST.in file, I think that the wheel distribution should have as little as possible (IMHO). I would exclude almost everything except for code, LICENSE and the setup.py. But that's just my opinion. I don't know if we can make different packages for wheel and sdist. For sdist I would just add everything that's not related to our development process, leaving mostly files like setup.cfg (it just holds information for dev as well), tox.ini, .travis.yml and etc out.

[harshanarayana]

@vltr I did a few tests with the new MANIFEST.in file and found the following

1. whl files only have the bare minimum contents as expected
2. sdist generates an uber tar with all the contents specified from this list.

I am yet to find out a way to explicitly configure what goes into whl and what goes into sdist.

[vltr]

That's interesting. I would expect the whl file to have the minimum contents, I just wanted to make sure it doesn't includes examples and tests (all containing .py files that, well, might get inside for some reason unknown). Now, the sdist I think would require the minimum to execute python setup.py install, the LICENSE and that would be it 😉

[vltr]

I have some docs to add myself to Sanic (so I can close #1329), but I think I'll just wait yours to be merged first because, well, it's almost like a complete overhaul 💪

[chenjr0719]

There are three requirement files, maybe load requirements from those files would be easier to maintain dependencies of Sanic?(cause we only have to focus on requirement files)
BTW, it seems that you change the way to run tests, this might also need to be documented at the contributing guide

[harshanarayana]

@chenjr0719 I like your suggestion. I need to clean up the requirements-dev.txt a bit before I can read and use it inside the setup.py. Let me get that sorted.

Btw, this doesn't alter the way to run tests. Just provides an extra way to run the test if you get the tarball from sdist and you want to run make test before you install sanic in your machine/environment. This is more of a consumer-facing feature than dev facing change.

[harshanarayana]

@chenjr0719 IMHO, I would love it if we can totally get rid of the requirements*.txt file and use extras_require for additional dependencies and tests_require for test related dependencies.

I am open to suggestion on this matter. I think not having a requirements*.txt file is much better option,

[chenjr0719]

@harshanarayana To be honest, I would prefer to use requirements*.txt files to manage my environment. That's why I propose this idea. But, after taking a look around some projects, use extras_require is also a good practice. Hum..., it hard to say which one is better or not cause this might also be influenced by the developer's habit.

Anyway, no matter using requiements*.txt files or use extras_require, please explain the usage at README.md or CONTRIBUTING.md.

[yunstanford]

Personally, for running test, i'd prefer tox to create test virtualenv with proper dependencies, or other tools, instead of setup.py/setuptools directly.

[harshanarayana]

@vltr Outside the .. code:: blocks. It's the new section I am trying to add that is causing this problem.

[vltr]

Have you tried \' or \" ?

[harshanarayana]

Yes, I tried that. No luck with that either.

[vltr]

Hmm ... Why don't you do this instead?

``pip3 install -e '[.docs]'``

[harshanarayana]

@vltr 👍 Ah this was a much nicer way to get around the problem. It even makes the document look nicer.

[vltr]

Since you're in the vibe ... Have you seen that there's different installation instructions in the project's README and in the docs?

[harshanarayana]

Since you're in the vibe ... Have you seen that there's different installation instructions in the project's README and in the docs?

Done. Fixed it across to be consistent and have the same details.

[vltr]

Nice!! This is awesome! Thanks, @harshanarayana !

[vltr]

Sweet! Em seg, 24 de dez de 2018 10:13, Harsha Narayana <[email protected] escreveu:

…

***@***.**** commented on this pull request. ------------------------------ In MANIFEST.in <#1424 (comment)>: > -recursive-exclude * *.py[co] +# Requirements +include *.txt + +# Tests +include tox.ini .coveragerc +graft tests + +# Examples +graft examples + +# Documentation +graft docs +prune docs/_build + +# Docker setup @ahopkins <https://github.com/ahopkins> Consider it done. I've added a make beautify with optional sort_imports=1 include_tests=1 to enable fixing import order using isort. It also has a simple make black and make isort task as well. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1424 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABeAs5g9m3R8jAWuSFgdnkdKdeLtcD_Vks5u8MUGgaJpZM4ZI5ej> .

[pypycoder]

cool, good improvement.

[yunstanford]

@harshanarayana Can you update this branch due to conflicts? will approve and merge in if no one objects.

[harshanarayana]

@yunstanford Rebased and resolved the conflict.