Lack of documentation

[rrooij]

First of all, I think youtube-dl is a great piece of software and I like the design. It's very modular and easy to add custom modules for sites.

But when I tried to implement my own extractor, it was hard to find what I need. I think the example in the README.md is a great start (the chapter 'Adding support for a new site'), but I think it needs more documentation.
For example, what to do when you encounter a certain type of site and what are the best ways to implement it. When trying Tweakers, I had no clue which tools I had to use, so I just downloaded the player page in search of the *.mp4 file.

If I had the knowledge of all the built-in methods, I would document it myself and do a pull request, but unfortunately, I don't have the knowledge to know which type of extraction should be used for which site.

And when does a site need an own extractor and when does it need a fix in the common extractor? I think those are good issues to document.

So in summary, I'd think those things would benefit from more documentation:

• When to use which helper tools (the ones in util)
• More info on adding support for a site (which methods should I use for which type of site, what is the cleaner way of doing things). For instance, my implementation of Tweakers.net would be considered "dirty", but I had no clue how to implement it correctly.

The youtube-dl project would benefit from this documentation by:

• Having more community activity
• Less feature-requests, more pull requests

[phihag]

I am wary of the trap of over-documentation; time and time again, I see a plethora of documentation becoming outdated, having to be maintained at great cost, and not actually being read. By just looking at the method names in utils and extractor.commons, it should be clear what helper functions are available.

The scope you suggest is huge; we could write a book on what media types there are alone, before considering to actually implement them, or write any extractors.

I propose what we already do now: Feel free to write your pull request with whatever Python code you want, and we will clean it up and use the proper helper methods. Only a minority of new sites can be handled with the generic extractor, and these cases, we will simply transplant the code.

I appreciate your enthusiasm, but it is with a heavy heart that I close this feature request. However, feel free to propose pull requests that do amend the documentation, but bear in mind that if you add an entry for every function there is, you're just replicating the actual list of functions. It may be better to sparkle a couple of hints in the example and surrounding text.

[rrooij]

It's OK. I think you're right.

I'm thinking about generating a documentation page with Sphinx or Pydoc, since most of the methods have a nice docstring. But developers can already generate the documentation themselves, so maybe it's not that needed.

Edit: Ah, I see. There's already a Sphinx conf.