-
Notifications
You must be signed in to change notification settings - Fork 8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
initalise repository with sphinx extensions #2
Conversation
a95603a
to
4f24db0
Compare
metomi/rose#2374 is a reference for usage. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Few typos, but no blockers.
Tried running make clean
, and make help
, and both worked fine. Then tried running some of the commands listed in make help
output (after installing via pip install -e .
). But the commands I tried failed with
(venv) kinow@kinow-VirtualBox:~/Development/python/workspace/cylc-sphinx-extensions$ make html
# build documentation
sphinx-autogen -i index.rst -o extensions
[autosummary] generating autosummary for: index.rst
[autosummary] writing to extensions
Running Sphinx v2.1.2
Extension error:
Could not import extension hieroglyph (exception: No module named 'hieroglyph')
Makefile:23: recipe for target 'html' failed
make: *** [html] Error 2
So installed again with pip install -e .[all]
. But make html
now failed with:
(venv) kinow@kinow-VirtualBox:~/Development/python/workspace/cylc-sphinx-extensions$ make html
# build documentation
sphinx-autogen -i index.rst -o extensions
[autosummary] generating autosummary for: index.rst
[autosummary] writing to extensions
Running Sphinx v2.1.2
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 25 source files that are out of date
updating environment: 25 added, 0 changed, 0 removed
reading sources... [100%] venv/lib/python3.7/site-packages/sphinx/templates/apidoc/toc
Warning, treated as error:
/home/kinow/Development/python/workspace/cylc-sphinx-extensions/venv/lib/python3.7/site-packages/sphinx/ext/autosummary/templates/autosummary/base.rst:3:Error in "currentmodule" directive:
maximum 1 argument(s) allowed, 3 supplied.
.. currentmodule:: {{ module }}
Makefile:23: recipe for target 'html' failed
make: *** [html] Error 2
But I think that may be OK as I haven't configured anything, and this is a repository for extensions, and not for the final documentation? I assume once we use it in a project with the right configuration, it will pass with no issues?
This PR is not breaking anything, so +1. Andthis is the first PR moving the old code here, so I think we canresolve the typos too if you prefer to fix them in another PR 👍
I've packaged dependencies a little strangely so that you don't have to install dependencies for all extensions to install some of the extensions. To install dependencies for a specific extension do: $ pip install -e [extension_name, ...] To install everything: $ pip install -e .[all] |
@kinow Sorry for not copying the fixes from cylc-doc. |
It was me being slow to read the README and check setup.py 👍 looking good, and with namespace and all. |
@wxtim volunteering you for you packaging experience. The code itself is old (moved from rose) so doesn't require much attention, the packaging, docs, setup etc is new and needs review. |
Seen - Now looking |
Fancy adding a license? |
Licence now on |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍
Migrate Sphinx extensions here from the
cylc/cylc-doc
andmetomi/rose
projects._static
) converted to Sphinx extensions.cylc.sphinx_ext
.The extension code has been reviewed in previous PRs, each extension is now documented with examples.
This repository is self documenting (run
make html
), the docs generated include explanations of each extension and example usage.Where to put the built documentation i'm not so sure, gh-pages would be the obvious choice but I'm not sure how that would work with our Cylc organisation setup. Will push this to #1