Skip to content
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.

Sign up for GitHub

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

Jump to bottom

docs: explain docs folder layout #1830

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: explain docs folder layout #1830

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions docs/source/developer_guide.rst
View file
Open in desktop
Copy link
Contributor

@DanicaSTFC DanicaSTFC Jun 12, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The additional information are great!

My main comment is "what do we mean by documentation?" Is it everything including the readme files, the website and also the docs? I think "Building documentation locally" should be the instructions on how to build the documentation (in the docs). Perhaps the title needs changing or we should split this into more sections. Like "Website" vs "Documentation i.e. the page Casper created. In this way it should be clearer.

Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,43 @@ Rendered
Building documentation locally
------------------------------

Folder layout:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Folder layout:
The `CIL/docs` folder containers the scripts and sources for building the CIL website and documentation. The folder contains:


- `README.md` - "QUICK START" rendered to `https://github.com/TomographicImaging/CIL`
- `.github/`

- `workflows/`

- `README.md` - "CI" rendered to `https://github.com/TomographicImaging/CIL/tree/master/.github/workflows`

- `docs/`

- `pages/` - landing (jekyll) source pages

- `_config.yml` - jekyll config file
- `_data/`

- `navigation.yml` - Header section
- `services.yml` - "Contact" footer section
- `network.yml` - "Thanks" footer section

- `XXX.md` - "WEBSITE" rendered to `https://tomographicimaging.github.io/CIL/XXX`

- `source/` - docs (sphinx) source pages

- `conf.py` - sphinx config file
- `XXX.rst` - "DOCS" rendered to `https://tomographicimaging.github.io/CIL/nightly/XXX`

- `docs_environment.yml` - sphinx dependencies
- `Gemfile*` - jekyll dependencies
- `Makefile` - common build scripts

- `mkdemos.py` - downloads demo notebooks to `source/demos/*.ipynb` & creates `source/demos.rst`

- `demos-template.rst`

- `mkversions.py` - creates `versions.json` used but sphinx docs version switcher

The easiest way to test documentation changes is to open a pull request and `download the rendered documentation from the CI <https://github.com/TomographicImaging/CIL/blob/master/.github/workflows/README.md>`_.

Alternatively, to build the docs locally, you will need a working ``cil`` installation.
Expand Down
Loading