A static website hosting Viking and Research IT related documentation.
Explore the docs »
Report Bug
·
Request Feature
Table of Contents
The website is hosted in S3 and delivered from a CloudFront distribution.
It is defined in cloudformation.yaml and deployed via GitHub Actions, although the SSL certificate is manually created and added to CloudFront through the AWS website.
The certificate is validated through DNS by adding the CNAMEs it provides, this can be done via a ticket to Systems.
The content is generated using sphinx with the rtd theme.
The source markdown files are stored in docs and the content is deployed via GitHub Actions.
There isn't a development server that auto-builds bundled with Sphinx. Create a new branch and make your changes. When your changes are ready to be deployed, submit a PR and request approval. Upon a merge the site is built and deployed to an S3 bucket and the CloudFlare cache is invalidated through GitHub actions.
Below is a step by step guide to getting up and running on Linux followed by an example on Windows. The built pages are static so once built the site is easily viewable in any web browser.
Python 3 and git.
-
Clone the repo
git clone [email protected]:university-of-york/research-it-documentation.git cd research-it-documentation/ -
Create a Python virtual environment and activate it
python3 -m venv .venv source .venv/bin/activate -
Install the required packages
python3 -m pip install -r requirements.txt -
Build the site
sphinx-build -b html docs/source site/ -a -
To view the site simply open the newly built
site/index.htmlin your browser
Python can be installed via Anaconda3 from the Software Center on a managed Windows PC (Git should already be installed), then from a PowerShell:
git clone https://github.com/university-of-york/research-it-documentation.git
cd research-it-documentation/
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
sphinx-build -b html docs/source site/ -a
To view the site simply open the newly built site/index.html in your browser
If needed, you can manually install the two required Python packages sphinx-rtd-theme and sphinx with:
python3 -m pip install sphinx-rtd-theme sphinx
The docs/source/replacements.py file contains a dictionary of replacement words to use throughout the docs. For exmaple, all the module versions to load in the jobscript examples. This makes it simple to update that part of the docs in the future.
The global.rst file contains an RST substitution so you can use |br| to create a raw html </br>. Useful in some formatting for example in the table headers. To use this substitution in a page you must include the following at the top of the page: .. include:: /global.rst
Found in the docs/source/_static/css/custom.css file. Only a minimal set of CSS tweaks are there as we keep close to the default theme.
Located in the assets/img and assets/data folders. The csv files in the data folder are useful for displaying tables with better formatting.
To help quickly make a new page, docs/source/template.rst can be used as a base.
Any .rst files dropped into the docs/source/applications folder will automatically be globbed and added to that section by the toctree directive in the docs/source/applications/index.rst page.
- Infrastructure
- Move site to AWS
- Fix issue with CloudFront cache invalidation
- Get ready for Pull Requests:
- Update README.md to new format
- Use public actions for workflow
- New pages:
- Create 'Data Management' section
- Add X11 Forwarding page
- Slurm common commands page
- Update pages:
- Update Virtual desktops page
- Move all application specific pages to one section
- Split up into separate pages
- FAQ page with common issues
- RELION jobscript
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Note
You may need to keep your pull request in sync with the base branch if other updates are also being added around the same time.
Research IT - [email protected]
Project Link: https://github.com/university-of-york/research-it-documentation
- othneildrew for the README.md template