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 <[email protected]

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
#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.