The Wayback Machine - https://web.archive.org/web/20200918082348/https://github.com/muammar/mkchromecast/issues/174
Skip to content

/ mkchromecast

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.

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: re-organization and update required. #174

Open
leamas opened this issue Apr 3, 2018 · 2 comments
Open

Documentation: re-organization and update required. #174

leamas opened this issue Apr 3, 2018 · 2 comments
Labels
documentation enhancement website

Comments

@leamas
Copy link
Contributor

@leamas leamas commented Apr 3, 2018 •
edited

Without being personal (this is a great project!), the documentation is a mess:

  • The --help info, which is supposed to be short and concise, is 263 lines, some of which too long.
  • The manpage (from debian packaging) which is supposed to give more detailed info, looks more or less like a placeholder.
  • The README.Debian file, which is supposed to contain info on distro-specific quirks is more or less a README.Linux, a file not heard of.
  • User info is also available in, of all places, __init.py__.
  • The mkchromecasr.com website lacks usage info, even links to it.
  • Same goes for README.md, the file facing users finding the github project.

I suggest central usage info is created somewhere, and just links to it from other places mentioned here.

I don't have the time or skills to do this, but I I had I think I would centralize the usage info to the manpage and, using man2html, publish it on the web. I would also move large part of the help info to the manpage, just leaving bare-bones options and parameter info. But there are certainly other ways to get this in shape.

See also discussion in #172.
@leamas leamas mentioned this issue Apr 3, 2018
Closed
@rbrito
Copy link

@rbrito rbrito commented Apr 5, 2018

The best way of making the documentation centralized and programmatically up-to-date that I have seen so far is with the approach taken by youtube-dl, where the documentation is in the program and the manpage is automatically generated from it (youtube-dl's Debian maintainer here).

In fact, even the readme is created from the program: https://github.com/rg3/youtube-dl/blob/master/Makefile#L72
@leamas
Copy link
Contributor Author

@leamas leamas commented Apr 5, 2018 •
edited

Perhaps. But mkchromecast is certainly much more complex than youtube-dl , and having all of the info in the code might bog it down. I can see s number of strategies:

  • The youtube-dl approach
  • Just hand-coding the manpage and publish it on the web.
  • Put most of the info in the website, and make the website part of the repo to handle versioning. That could certainly be combined with the youtube-dl approach.
  • Use a tool like doxygen which can combine general parts written in html with code documentation. API-centric, but might work.
  • Use a modern XML-based format like DocBook and build the docs from that
  • Use one of the tools in the python documentation tools mess: [1]

This list is far from comprehensive. The final decision how to make it must be taken by a person who actually is going to do the job. And that's not me, for sure.

[1] https://wiki.python.org/moin/DocumentationTools

EDIT: Added python tools
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation enhancement website
3 participants
@rbrito @leamas @muammar
You can’t perform that action at this time.