FEAT: Add Jupinx CLI for building Jupinx Style Sphinx Projects

[AakashGfude]

Set up a basic functionality of using make commands using command line jupinx tool.

The options at present are :-

1) jupinx [-w] [--website] - which runs make website in the background 2) jupinx [-j] [--jupyter] [-n] [--notebooks] which runs make jupyter in the background 3) jupinx [-c] [--coverage] which runs make coverage in the background

The template for html is at present stored in this repos templates\html folder.

running only jupinx in the command line with options will show a minimim help tool. and running jupinx [--help] [-h] will show a more descriptive help tool, both of which @mmcky will document properly.

[jstac]

Thanks guys!

Since we're making a clear break from the past, let's just have jupinxr -n and jupinx --notebooks. We can drop jupinx -j and jupinx --jupyter.

Should we add a --parallel flag for jupinx --website? Plus jupinx -wp?

Question: should we point it to the dir, as in jupinx -n ~/some_dir/lecture_source_repo? That seems more natural for a binary...

That coincides with usage of something like LaTeX (latex filename) or Jupyter book (jupyter book build source_repo).

If no target is given, jupinx can give an easily understood error message.

[mmcky]

thanks @jstac. That should be fine.

If you run jupinx at the root level of a repository do you think we need to specify jupinx -n ./?

[jstac]

I wondered about that too.

I guess we could allow jupinx -n or jupinx -w without further arguments if we're at the root level of the repo, as long as a sensible error is triggered in other cases. ("No conf.py file found. Please change to the root level of the source file directory and try again, or specify a path. See the man page for examples.")

[jstac]

See the man page -> Type man jupinx for more information and examples.

[mmcky]

hey @jstac the man page is a very linux based thing and needs to be installed into the correct locations to make it work etc. Are you set on having a man page? An alternative would be to have a comprehensive jupinx -h or jupinx --help that provides information similar to the man page? This would be platform independent.

If you want a man page we can look into this too.

https://askubuntu.com/questions/244809/how-do-i-manually-install-a-man-page-file

Creating man page:

https://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/

[jstac]

I see. Then let's stick to jupinx -h and jupinx --help.

[mmcky]

OK - thanks @jstac. We will implement jupinx -h and jupinx --help for now. If you find you want one -- we can always check for linux on install and try and write to the /usr/local/man location. Hopefully that location is consistent across linux types.

[AakashGfude]

Following additional functionalities have been added :-

• parallel option in jupinx command :: example :- jupinx -w --parallel=4 . Here, the value of the --parallel argument is the number of cores. If no value is provided to the --parallel option, then the default is taken as 2 cores. If no --parallel is specified then it runs sequentially.
• -d , --directory option in jupinx command :: example jupinx -d DIRECTORY_PATH . If no DIRECTORY_PATH is specified, then it throws an error about specifying it. If no -d option is specified, then it takes the current directory as the working directory.

[mmcky]

thanks @AakashGfude

• [x] @mmcky to update the docs/sphinx with options as implemented.

@AakashGfude would you mind to update with the latest master branch?

[mmcky]

@AakashGfude just to clarify.

• [x] Does -d, --directory option require an = to assign path or not?

[mmcky]

• [x] adjust rtd theme: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html to fix table width issue.

[jstac]

Hey guys, can we please leave the -d option out?

I would expect this tool to function like LaTeX:

pdflatex --shell-escape mydoc.tex

The only difference is that we're pointing at a directory:

jupinx --website lecture-source-py

Thus, jupinx is supplied with options and an argument (the target, in this case lecture-source-py). If no argument is given, then jupinx tries . as the argument (or just fails with a useful error message, I don't mind).

[jstac]

Oh, and it would be great if tab expansion works for the argument, so we can type jupinx -w lec and hit the tab key.

[mmcky]

thanks @jstac -- certainly happy to make that change.

In my thinking (from a usability perspective) I think most of the time users will want to trigger builds while they are inside the repo so being able to run the build without specifying a directory is important I think. If you're editing it might get frustrating to cd .. then jupinx -n lecture-source-py each time you wanted to build. The main difference here (from latex) is going from file to directory as the path. Specifying a directory will be super helpful from a build server perspective which is why we set it up with the -d, --directory option.

I think it would be even better if it worked like git where you can trigger at any level of the repository (i.e. in source/rst even) and is based on being inside a jupinx repo -- but that would take a bit of work to get paths right etc.

[mmcky]

I had always thought tab expansion was a shell driven thing. @AakashGfude do you know how that mechanism works?

[mmcky]

• [x] this looks promising https://argcomplete.readthedocs.io/en/latest/

[mmcky]

@AakashGfude perhaps we should take a look at using a framework such as https://github.com/python-cmd2/cmd2 which provides things like auto-complete for arguments?

[jstac]

Thanks @mmcky for your thoughts. That's not my preference but, as a compromise,

1. please make the change, so there is no -d option before the directory (the model is command --options argument)

2. if there's no target specified then jupinx defaults to .

I suspect that tab expansion will be easier if you follow this path (as compared to --directory=need_to_tab_expand _this).

[mmcky]

@jstac Sure.

@AakashGfude when you're in this afternoon - let's focus on the directory change as requested above. Thanks.

[mmcky]

• [x] @mmcky to revise docs for removal of -d, --directory

[mmcky]

Added https://github.com/QuantEcon/jupinx/issues/24 to track argument autocompletion so this branch can be merged after the -d change.

[jstac]

Like git, typing just jupinx could provide the same output as jupinx --help.

Actually, the git output is a good model for jupinx (type git on the command line to see their help, which is nicely written).

[AakashGfude]

@jstac @mmcky autocompletion of the directory path as mentioned by @jstac in the comment below works fine at the moment, autocompletion of arguments will be targeted in issue #24

Oh, and it would be great if tab expansion works for the argument, so we can type jupinx -w lec and hit the tab key.

[mmcky]

@jstac the current help looks like:

(base) mmcky:cmd matthewmckay$ jupinx --help
usage: jupinx [OPTIONS] <PROJECT-DIRECTORY>

Jupinx command line tool.

Provides a collection of utilities for Jupyter and Sphinx Projects.
If you would like to setup a new project please use: jupinx-quickstart.

positional arguments:
  directory             provide path to a project directory (optional)

optional arguments:
  -h, --help            show this help message and exit
  -c, --coverage        compile coverage report for project (result:
                        _build/coverage/reports/{filename}.json
  -n, --notebooks       compile a collection of Jupyter notebooks (result:
                        _build/jupyter)
  -w, --website         compile a website through Jupyter notebooks (result:
                        _build/website/
  --version             show program's version number and exit

additional arguments:
  --parallel [PARALLEL]
                        Specify the number of workers for parallel execution.
                        [Default --parallel 2]

Examples:
    jupinx --notebooks (within a project directory)
    jupinx -n lecture-source-py (specify path to project directory)

Further documentation is available: https://quantecon.github.io/jupinx/.

[mmcky]

thanks @AakashGfude I am happy with this branch now. Looking good. I think we can merge and iterate from here as required. When merged I will do some testing of the tool next.

thanks @jstac for your input. I think we have met all your requests (except argument autocomplete which we have opened an issue for). I would like to merge this to setup initial PyPI release so we can start doing some testing.

[jstac]

Thanks @mmcky .

@AakashGfude says he already has autocomplete of the argument (i.e., directory) working. That's all that I asked for. So you've met all of my requests.

Great work guys, please go ahead.

[mmcky]

thanks @jstac just to clarify -- the directory autocomplete comes with sh that we are using for free (i.e. jupinx didn't need to support that). Please let us know if your shell doesn't do the path directory autocomplete and we can look into it further.