Add documentation #62
Conversation
|
To build: Install the |
Codecov Report
@@ Coverage Diff @@
## master #62 +/- ##
=======================================
Coverage 76.76% 76.76%
=======================================
Files 9 9
Lines 1278 1278
Branches 153 153
=======================================
Hits 981 981
Misses 250 250
Partials 47 47Continue to review full report at Codecov.
|
|
Mh... I mean we have no real API doc so far anyway... I'll need to think about this. Would definitely like to migrate to Sphinx later (converting the Markdown files is easy). |
|
That'll be easy, but it's better to have non-sphinx docs than to have no docs. |
| recommend using [venv](https://docs.python.org/3/library/venv.html) to create | ||
| an isolated Python environment. | ||
|
|
||
| $ python3 -m venv venv |
There was a problem hiding this comment.
While you're at it, can you patch this in the readme, too?
docs/docs/testcerts.md
Outdated
| during the next 5 years: | ||
|
|
||
| $ openssl req \ | ||
| -newkey rsa:1024 \ |
There was a problem hiding this comment.
I'd say 4096. Sure, it's a test certificate but you know... people do stupid things and I don't want to be responsible. 😉
There was a problem hiding this comment.
The certificate is only valid for localhost. I don't think there's much harm that can be caused by that. Do you think there's any value in >1024?
There was a problem hiding this comment.
I was thinking of people that generate production certs and are looking for examples.
docs/docs/testcerts.md
Outdated
| -config <(cat /etc/ssl/openssl.cnf \ | ||
| <(printf '[SAN]\nsubjectAltName=DNS:localhost')) \ | ||
| -sha256 \ | ||
| -days 1825 |
There was a problem hiding this comment.
Capping to 90 days should be sufficient. One doesn't want a test cert to be valid for a long period of time if it's meant for short-term testing. In case one forgets to delete it from Chrome, it can't do any harm (for long).
There was a problem hiding this comment.
To be honest it's a huge PITA having to generate a new test-cert and having to import it both into Firefox and Chrome every time I want to run SaltyRTC tests (which is often more than 90 days apart).
There was a problem hiding this comment.
Yes but you are an intelligent being that can adjust this parameter. 😉
docs/mkdocs.yml
Outdated
| @@ -0,0 +1,21 @@ | |||
| site_name: SaltyRTC Server | |||
| site_description: Documentation for saltyrtc-server-python. | |||
| site_author: Lennart Grahl | |||
|
Updated! |
| recommend using [venv](https://docs.python.org/3/library/venv.html) to create | ||
| an isolated Python environment. | ||
|
|
||
| $ python3 -m venv venv |
|
Actually I'd link to the docs from the README file. There's no advantage in keeping the information in two places and always having to sync the docs and the README. But for that I'd have to set up automated test building etc. Should I? |
What do you mean by that? |
|
Setting up automated builds of the docs through Readthedocs, triggered by successful tests :) Once we have always-up-to-date docs, we can link to them from the README and remove the instructions from the README. |
|
@lgrahl still interested in this? |
|
I think it's a good reminder that we need docs and this is a good start. Let's leave it open. |
Argh, I only saw your
docsbranch once I pushed mine.Anyways, here's documentation implemented using mkdocs, which is a bit simpler and faster than sphinx. It does not support generating API docs, but I think API docs are overrated anyways and prose is much more important.
If you like this I can set up auto builds with Travis on Readthedocs.
Refs #2