semanticClimate automated publication proof-of-concept
Thank you to all the hackathon participants, the semanticClimate team and especially Summer 2023 Interns and scientific staff from the ICAR-National Bureau of Plant Genetic Resources (ICAR-NBPGR), India, who contributed to the ‘mockup’ prototype: Cities (Mahvish Fatma, Renu Kumari, Waheb Mehdi), Mountains and Glaciers (Shiwani Yadav), and Food Security (Yasin Jeshima senior scientist from ICAR-NBPGR). Thank you to Peter Murray-Rust, Gitanjali Yadav, and Shweata Hegde for pushing semanticClimate forward and making dreams become reality. To Simon Bowie of the COPIM project and Centre for Postdigital Cultures – Coventry University, UK for the code contribution for the HTML to Markdown converter. ADA Semantic Publishing Pipeline is from the NextGenBooks service provided the Open Science Lab, TIB, and supported by NFDI4Culture research as part of the National Research Data Infrastructure Germany (NFDI).
To clone this repository from GitHub, ensure that Git is installed on your local machine either as a command line interface (https://git-scm.com/) or through GitHub Desktop (https://desktop.github.com/).
Use either the CLI or GitHub Desktop to clone the repository into your preferred installation directory.
If using CLI, navigate in the terminal to your preferred installation directory and run:
git clone https://github.com/SimonXIX/quarto_semanticclimate.git
To install all prerequisites for running this repository on your local machine, please follow the instructions below.
First, install Python following the instructions at https://www.python.org/downloads/
Once Python is installed, navigate to the quarto_docker directory in terminal and run:
pip install -r requirements.txt
This should install all the required Python modules for running the Quarto rendering process.
Next, install the Quarto CLI following the instructions at https://quarto.org/docs/get-started/
Finally, install an environment for viewing and editing Jupyter Notebook files. This can be Visual Studio Code (https://code.visualstudio.com/), the open source fork VSCodium (https://vscodium.com/), or a dedicated Jupyter environment like JupyterLab (https://quarto.org/docs/get-started/hello/jupyter.html).
It's possible (though not required) to use Docker to run the environment for Jupyter Notebook running and Quarto rendering.
This process works in Linux but does not work in macOS due to a known issue. This involves Quarto not running properly in the Docker container in macOS due to the amd64 emulation of Docker Desktop for arm64 MacOS. See discussion at quarto-dev/quarto-cli#3308. This shouldn't occur in any other environment running Docker.
To run in Docker, first install Docker Desktop following the instructions at https://docs.docker.com/desktop/.
Once installed, navigate in the terminal to the directory for the cloned Git repository.
Run docker-compose up -d --build to start the containers.
The jupyterlab container runs a stand-alone version of JupyterLab on http://localhost:8888. This can be used to edit any Jupyter Notebook files in the repository. The JupyterLab instance runs with the password 'jupyterlab'.
The nginx container runs Nginx webserver and displays the static site that Quarto renders. This runs at http://localhost:1337.
The quarto container starts a Ubuntu 22.04 container, installs various things like Python, downloads Quarto and installs it, and then adds Python modules like jupyter, matplotlib, and panda. It then runs in the background so Quarto can be called on to render the qmd and ipynb files into the site/book like so:
docker exec -it quarto quarto render
When you're finished using the code, run docker-compose down to stop the containers.
The main publishing workflow uses Quarto to render the output of Jupyter Notebook files.
You can edit the .ipynb files in whatever Jupyter environment you installed above. After editing, ensure that you run the Notebook.
If you're running the code locally, you can then navigate to the repository directory in terminal and run:
quarto render
for Quarto to render the output into an output directory, in this case, ./docs.
To preview the published publication, navigate to ./docs/index.html and open it in a web browser. You should see the entire published site.
When pushed to GitHub, GitHub Pages will then serve the HTML files in the ./docs directory as a website.
Content - © 2023 The authors. Creative Commons Attribution-ShareAlike 4.0 https://creativecommons.org/licenses/by-sa/4.0/
ADA code - © 2023 The authors. GNU General Public License v3.0 https://github.com/TIBHannover/ADA/blob/main/LICENSE
Data - All data and data sets produced would be CC 0, Public Domain, https://creativecommons.org/publicdomain/zero/1.0/
All fonts and graphics and media production software used on the production would be OSI compliant.
FAIR principles would also be applied https://www.go-fair.org/fair-principles/
All third party content and code is the copyright of the authors and under their respective OSI compliant open licenses for code and compliant with Creative Commons Attribution-ShareAlike 4.0 International for content.