This repository has been archived by the owner on Oct 1, 2020. It is now read-only.
Refactor docs #3
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 16 commits
February 11, 2020 12:19
Refactor most of `docs/docs/index.md` to 120 character line width; some URLs are longer than 120 line width, so have been left as is. Also revised the `README.md` files across the project to have a 120 line width maximum. Add a `docs/_static` folder for Sphinx builds, and refactor the line widths of `index.rst` and `conf.py` to 120 characters.
`test_folders` is originally: ```python set(abs_expected_dirs + ignored_dirs) - set(abs_dirs) ``` This is the folders in `set(abs_dirs)` not in `set(abs_expected_dirs + ignored_dirs)`. However, it does NOT check the reverse, i.e. folders in `set(abs_expected_dirs + ignored_dirs)` not in `set(abs_dirs)`. In this case, the test always passes.
List all items in alphabetical order with files first, followed by folders.
The `.envrc` file replaces the existing `.env` file. Also detail how to import these environmental files, and to set up and import a `.secrets` file as well.
Use the common configuration file listed on the GDS Way. See here: https://gds-way.cloudapps.digital/manuals/programming-languages/python/linting.html#common-configuration for more details.
Comment out option from `Makefile`, and also remove now redundant `data` rule.
Also set Python 3 as default throughout the cookiecutter project.
`autodoc` allows automatic documentation generation from docstrings. `napoleon` allows docstrings to be in Google or NumPy format, as well as reStructuredText format, which is the default.
`autosummary` creates stub pages for each and every function. `recommonmark` allows Sphinx to parse Markdown as well as reStructuredText. Also add `sphinx-markdown-tables` to parse Markdown tables correctly. Also exclude the `pull_request_template.md` from Sphinx build.
Combine the two files, and consolidate the documentation to refer to the `Makefile`, and all possible `make` rules. Move this combined Markdown file into a sub-folder for clarity.
Refactor `index.rst` to `index.md`, and use `recommonmark.transform.AutoStructify` to enable reStructuredText transformations in Sphinx.
Remove `{{ cookiecutter.repo_name }}/references` folder as well, and
edit folder organisation diagrams.
Edit `pull_request_template.md` to reflect these changes.
Also add all TOC references, as required.
Also fix all folder organisation charts to reflect changes. Amend `README.md`s for consistency, and any associated tests.
Ensure information about AQA documents is clearly marked. Ensure links in `pull_request_template.md` work correctly (relative to GitHub); add tests to check this.
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Revised cookiecutter structure, and associated docs.
Main revisions are: