Idea: `rtd` cli script instead of standalone `rtd-build`

[gregmuellegger]

The name rtd-build is very explicit about what it does, that's cool. But it doesn't allow more flexible use cases later on. For example: it should be really easy to get started with a sample readthedocs.yml file. That could be done by a command like rtd init.

rtd build is then a subcommand that does what rtd-build is currently doing. That naming scheme allows for further extension, like:

• rtd test: test for syntax and configuration issues in the yml file. It could also check your conf.py for problems etc.
• rtd lint: test your documentation against heuristics about common mistakes in writing docs (similiar to what annotatedocs had as goal) etc.
• rtd upload: build your docs with crazy dependencies and then upload it
• rtd register: take the repo url from git's origin remote and try to register this project on readthedocs.org

I know that this is nothing that will happen in the very near future because making the build work first is the most precious thing, but I wanted to record and discuss those thoughts here.

[ericholscher]

Yea, had this idea in the past: https://pypi.python.org/pypi/rtd -- Just need to implement it :)

On Thu, Jun 18, 2015 at 10:54 AM, Gregor Müllegger <notifications@github.com

wrote:

The name rtd-build is very explicit about what it does, that's cool. But it doesn't allow more flexible use cases later on. For example: it should be really easy to get started with a sample readthedocs.yml file. That could be done by a command like rtd init.

rtd build is then a subcommand that does what rtd-build is currently doing. That naming scheme allows for further extension, like:

• rtd test: test for syntax and configuration issues in the yml file. It could also check your conf.py for problems etc.
• rtd lint: test your documentation against heuristics about common mistakes in writing docs (similiar to what annotatedocs had as goal) etc.
• rtd upload: build your docs with crazy dependencies and then upload it
• rtd register: take the repo url from git's origin remote and try to register this project on readthedocs.org

I know that this is nothing that will happen in the very near future because making the build work first is the most precious thing, but I wanted to record and discuss those thoughts here.

— Reply to this email directly or view it on GitHub https://github.com/rtfd/readthedocs-build/issues/3.

Eric Holscher Maker of the internet residing in Portland, Oregon http://ericholscher.com

[gregmuellegger]

I can recommend the click library for this. It's made for having independent subcommands and really makes writing CLIs fun. So much better than any argparse can be :) and the docs are awesome.

[d0ugal]

+1 to the idea and to using click.