rtd updates

[RCarter-IDM]

RTD review of pacakge - completed the following:

• moved .readthedocs.yml to root (required)
• copyright from IV to BMGF in conf.py
• updated docs/requirement.txt to closer align w/ the one used in idmtools

[RCarter-IDM]

@devclinton, @JSchripsema-IDM, please take a look at my suggested changes. Jen, feel free to add additional suggestions - as needed. Clinton, when I tried to test by doing a local build in Windows, it didn't like the use of {{ w/in the path. Here's the results:

C:\github\cookiecutter-python-library{{ cookiecutter.library_name }}\docs>make html C:\github\cookiecutter-python-library{{ cookiecutter.library_name }}{{ is not a directory. The syntax of the command is incorrect.

[devclinton]

@devclinton, @JSchripsema-IDM, please take a look at my suggested changes. Jen, feel free to add additional suggestions - as needed. Clinton, when I tried to test by doing a local build in Windows, it didn't like the use of {{ w/in the path. Here's the results:

C:\github\cookiecutter-python-library{{ cookiecutter.library_name }}\docs>make html C:\github\cookiecutter-python-library{{ cookiecutter.library_name }}{{ is not a directory. The syntax of the command is incorrect.

You need to generate a new project from the template. I need to add some better instructions, but the general steps are

pip install cookiecutter
cookiecutter path/to/local_repo

[RCarter-IDM]

@devclinton, after moving yml back and merging in all of Jen's changes (thx Jen!), I'm testing 'make html' on local branch (first following above mentioned steps: pip install cookiecutter, cookiecutter path/to/local_repo. @devclinton, question: will there be api docs needed w/ this package? The reason I'm asking is because the first message/error I receive (after running 'make html') is the following:

(cookie) C:\github\cookiecutter-python-library\my_library_name\docs>make html usage: sphinx-apidoc [OPTIONS] -o [EXCLUDE_PATTERN, ...] sphinx-apidoc: error: argument -o/--output-dir: expected one argument The system cannot find the file specified.

[RCarter-IDM]

@JSchripsema-IDM, I'm getting the following two errors (see below) when attempting to do local build (after first doing these steps: pip install cookiecutter & cookiecutter path/to/local_repo). Just checking to see if you're familiar w/ resolution from your previous doc package conversion work from ghpages to rtd.

Traceback (most recent call last): File "c:\cookie\lib\site-packages\sphinx\config.py", line 326, in eval_configfile execfile(filename, namespace) File "c:\cookie\lib\site-packages\sphinx\util\pycompat.py", line 88, in execfile_ exec(code, _globals)

FYI, 'cookie' in the path represents my python venv, cookie.

[RCarter-IDM]

@devclinton, FYI, here's the function regarding first traceback error (Note, that it is identical to the one that works w/ idmtools):

def eval_config_file(filename: str, tags: Tags) -> Dict[str, Any]: """Evaluate a config file.""" namespace = {} # type: Dict[str, Any] namespace['file'] = filename namespace['tags'] = tags

with cd(path.dirname(filename)):
    # during executing config file, current dir is changed to ``confdir``.
    try:
        execfile_(filename, namespace)
    except SyntaxError as err:
        msg = __("There is a syntax error in your configuration file: %s\n")
        raise ConfigError(msg % err) from err
    except SystemExit as exc:
        msg = __("The configuration file (or one of the modules it imports) "
                 "called sys.exit()")
        raise ConfigError(msg) from exc
    except ConfigError:
        # pass through ConfigError from conf.py as is.  It will be shown in console.
        raise
    except Exception as exc:
        msg = __("There is a programmable error in your configuration file:\n\n%s")
        raise ConfigError(msg % traceback.format_exc()) from exc

return namespace

[RCarter-IDM]

And, same w/ 2nd error for pycompat.py (works w/ idmtools, but not cookiecutter-python-library):

def execfile_(filepath: str, _globals: Any, open: Callable = open) -> None: from sphinx.util.osutil import fs_encoding with open(filepath, 'rb') as f: source = f.read()

# compile to a code object, handle syntax errors
filepath_enc = filepath.encode(fs_encoding)
try:
    code = compile(source, filepath_enc, 'exec')
except SyntaxError:
    # maybe the file uses 2.x syntax; try to refactor to
    # 3.x syntax using 2to3
    source = convert_with_2to3(filepath)
    code = compile(source, filepath_enc, 'exec')
    # TODO: When support for evaluating Python 2 syntax is removed,
    # deprecate convert_with_2to3().
    logger.warning(__('Support for evaluating Python 2 syntax is deprecated '
                      'and will be removed in Sphinx 4.0. '
                      'Convert %s to Python 3 syntax.'),
                   filepath)
exec(code, _globals)

[JSchripsema-IDM]

@devclinton Predictably, my doc build broke because my dummy package doesn't actually exist. I removed or commented out the generate-api and import statements for my dummy package to see if I could get a minimal set of docs building. It ends up stock on the glossary with an error I've never seen before:

writing output... [ 25%] glossary Theme error: An error happened in rendering the page glossary. Reason: UndefinedError("'cookiecutter' is undefined")

I tracked this down to issues with the cookiecutter variable inside {{}} not resolving correctly in the breadcrumbs.html and footer.html files under _templates. When I replace those with plain text, I can get a successful build. I think we need some other way of automatically inserting the package name into those HTML files. The over and underlines in topic titles also end up too short for most package names--not a big deal, but would be a nice thing if we could automatically extend those to match the length of the topic title.

[devclinton]

Let me generate a new project today and document minimal steps with this branch.

I will also look at the html in templates. It may need its extension changed in template for cookiecutter to process it.

[devclinton]

@RCarter-IDM - Sorry for delay. I should be able to get back to this tomorrow.

[JSchripsema-IDM]

@devclinton what needs to happen to resolve this? A few new packages have been spun up using this cookiecutter template with very outdated doc files that don't have the correct breadcrumbs, footer, search, etc.