search

bitpanda-labs / loggo2

Open source Python logging utilities
MIT License
4 stars 12 forks source link

Generate a readthedocs page with mkdocs? #97

Open interrogator opened 5 years ago

interrogator commented 5 years ago

I recently set up readthedocs via mkdocs on another module of mine, it was easy and works nicely.

https://buzz.readthedocs.io/en/latest/

Would take 15 mins to set up for loggo using the README as the main page, but I'm not sure we should. Pros and cons are pretty obvious.

Have mentioned this before, but would like to reach a final decision. I lean toward a yes purely because I think it's kind of cool.

hukkin commented 5 years ago

Would this add anything that the readme doesnt already provide? If no, then i'd probably vote no simply for no added value but some small maintenance.

interrogator commented 5 years ago

Various small things: having a dedicated docs host, sidebar TOC for better navigation readability, ability to have multiple markdown pages, images, and status reports if docs fail to build. Then various fringe things like PDF building, support for different languages, stable vs latest docs, IDK.

One nice thing is that readthedocs kind of encourages you to add more docs and fill out the space, whereas in a gh readme the pressure is to be concise. So going with the former could lead to more comprehensive docs if we thought that necessary.

Of all benefits, I think the main two are:

  1. simply being on readthedocs, which some users gravitate toward when they want docs
  2. Having a two-level TOC sidebar, which would help navigation of docs quite a bit

Fairly small benefits, but also small maintenance.

jpwood commented 5 years ago

If you pull this branch and run mkdocs serve you can see what it would look like.

I just took the README.md and turned it into pages.

jpwood commented 5 years ago

My input is it looks nice. To make it a bit more useful we would probably have to improve it to be a bit more thorough as a user guide. But that's just a case of adding text.

interrogator commented 5 years ago

Yeah, I think it's cool. We could probably just ln README to docs/index.md to save maintaining different text files though. TOC would be the same if we made sure the levels were right in README...

interrogator commented 5 years ago

or, turn README into the bare basics plus a link to readthedocs, and then flesh out the docs/ files.

jpwood commented 5 years ago

I think if we're just taking the README it might not be worth it.

If you want to make a bit more thorough documentation it might be worth it.

interrogator commented 5 years ago

Yes, so the question is, do we think we need more documentation and examples? I think more comprehensive docs would be good, we could have a graylog section with screenshots, a section on how to set up loggo for django, etc. Maybe also a section on subclassing, with custom obfuscation and so on. These wouldn't really fit in the README, and would justify the use of mkdocs.

I say, if we think it's good to add more docs, we should definitely do it via rtd, reducing what is in README to just the basics.

So, do we feel we've documented enough, or not? @hukkinj1 @gcarq final answers?

hukkin commented 5 years ago

If somebody comes up with useful additional documentation that would justify this, I'm not against it at all. But I don't think loggo is that complex that it would need it, I think the readme is fine for now.

Stuff like subclassing I think is probably really out of scope of what our docs should provide. If you're good enough programmer to consider that, surely you can manage to subclass loggo just like any other class.

interrogator commented 5 years ago

I mostly agree, though in our case subclassing for obfuscation is at least worth noting, since almost everyone doing obfuscation will have their own routines, and loggo is designed so that these can be plugged in. This is to say, I wouldn't mind one entry in a TOC about subclassing for this purpose. That can go on the list of 'docs that if somebody writes may justify the use of mkdocs'.