From ba8b05a56b35b47c4627404d1d5373c6b9196182 Mon Sep 17 00:00:00 2001 From: Tek Raj Chhetri Date: Tue, 18 Feb 2025 23:34:23 -0500 Subject: [PATCH] heritage graph documentation init --- .github/workflows/codespell.yml | 2 +- .github/workflows/deploy_docs_githubpages.yml | 62 ++++++++ documentation/Makefile | 20 --- documentation/conf.py | 36 ----- documentation/contributing.rst | 132 ------------------ documentation/index.rst | 53 ------- documentation/introduction.rst | 6 - documentation/make.bat | 35 ----- documentation/my_module.rst | 0 documentation/requirements.txt | Bin 1086 -> 0 bytes 10 files changed, 63 insertions(+), 283 deletions(-) create mode 100644 .github/workflows/deploy_docs_githubpages.yml delete mode 100644 documentation/Makefile delete mode 100644 documentation/conf.py delete mode 100644 documentation/contributing.rst delete mode 100644 documentation/index.rst delete mode 100644 documentation/introduction.rst delete mode 100644 documentation/make.bat delete mode 100644 documentation/my_module.rst delete mode 100644 documentation/requirements.txt diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml index 6681edec9..c01f4eead 100644 --- a/.github/workflows/codespell.yml +++ b/.github/workflows/codespell.yml @@ -4,7 +4,7 @@ name: Codespell and Docs Generation on: push: - branches: [main, dev] + branches: [main, documentation] pull_request: branches: [main] diff --git a/.github/workflows/deploy_docs_githubpages.yml b/.github/workflows/deploy_docs_githubpages.yml new file mode 100644 index 000000000..8da3c7041 --- /dev/null +++ b/.github/workflows/deploy_docs_githubpages.yml @@ -0,0 +1,62 @@ +#https://jupyterbook.org/en/stable/publish/gh-pages.html +name: Deploy Jupyter Book + +# Run this when the master or main branch changes +on: + push: + branches: + - master + - documentation + # If your git repository has the Jupyter Book within some-subfolder next to + # unrelated files, you can make this run only if a file within that specific + # folder has been modified. + # + # paths: + # - some-subfolder/** + +# This job installs dependencies, builds the book, and pushes it to `gh-pages` +jobs: + deploy-book: + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + steps: + - uses: actions/checkout@v3 + + # Install dependencies + - name: Set up Python 3.11 + uses: actions/setup-python@v4 + with: + python-version: 3.11 + + - name: Install dependencies + run: | + pip install -r docs/requirements.txt + + # (optional) Cache your executed notebooks between runs + # if you have config: + # execute: + # execute_notebooks: cache + - name: cache executed notebooks + uses: actions/cache@v3 + with: + path: docs/_build/.jupyter_cache + key: jupyter-book-cache-${{ hashFiles('requirements.txt') }} + + # Build the book + - name: Build the book + run: | + jupyter-book build docs/ + + # Upload the book's HTML as an artifact + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: "docs/_build/html" + + # Deploy the book's HTML to GitHub Pages + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 + diff --git a/documentation/Makefile b/documentation/Makefile deleted file mode 100644 index bc9a7c7c7..000000000 --- a/documentation/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = docs - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/documentation/conf.py b/documentation/conf.py deleted file mode 100644 index 5fd0aa198..000000000 --- a/documentation/conf.py +++ /dev/null @@ -1,36 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -import os -import sys -sys.path.insert(0, os.path.abspath('../')) - -project = 'heritagegraph' -copyright = '2024, CAIR-Nepal' -author = 'CAIR-Nepal' -release = '0.1' - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.napoleon', # If you want Google-style or NumPy-style docstrings - 'sphinx.ext.viewcode', # Adds links to the source code of functions/classes -] - -templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = 'sphinx_rtd_theme' -html_static_path = ['_static'] - diff --git a/documentation/contributing.rst b/documentation/contributing.rst deleted file mode 100644 index 725171ab7..000000000 --- a/documentation/contributing.rst +++ /dev/null @@ -1,132 +0,0 @@ -.. HeritageGraph documentation master file, created by sphinx-quickstart on Wed Nov 20 22:11:10 2024. - -Contributing to HeritageGraph -============================= - -Thank you for your interest in contributing to **HeritageGraph**! We are happy to have you join our community and help us build a platform dedicated to preserving and sharing Nepalese cultural heritage through digital means. Your contributions, whether big or small, will have a significant impact on our mission. - -Overview of the Project ------------------------- - -**HeritageGraph** project consists of three primary components: - -1. **Frontend (React.js)**: - The frontend is built with **React.js (version 18.0.2)**. It provides an interactive and responsive user interface for browsing and interacting with the platform. - -2. **Backend (Django Rest Framework)**: - The backend is powered by **Django Rest Framework (DRF)**, which handles user authentication, form submissions, data processing, moderation, and more. It acts as the backbone of the platform, ensuring seamless communication between the frontend and the database. - -3. **Drupal-DKAN (Data Distribution)**: - **Drupal-DKAN** is used for data distribution. It enables the structured distribution of cultural heritage data, making it accessible and interoperable across different systems. - -How You Can Contribute ------------------------ - -We welcome contributions from everyone, regardless of experience level. Here’s how you can get started: - -To begin contributing, first, fork the repository to your own GitHub account. This will create a personal copy of the project where you can work on your changes. Make sure to fork all the branches too. - -**Choose an Area to Contribute** - You can contribute to one of the following areas: - - - **Frontend (React)**: - Work on improving the user interface, fixing bugs, or adding new features. If you have suggestions for improving user experience (UX) or accessibility, we encourage you to contribute! - - - - git clone -b dkandev https://github.com/CAIRNepal/CHLOD.git - - Navigate to the `CHLOD/` directory: - - - cd CHLOD/docroot/frontend - - Install dependencies: - - npm install - - And run the project: - npm run start - - You can view the frontend on `localhost:3000`. - - - **Backend (Django Rest Framework)**: - Contribute to the API endpoints, authentication, or backend logic. Help optimize and enhance the functionality of our backend. - - - - git clone -b django https://github.com/CAIRNepal/CHLOD.git - - Navigate to the backend directory: - - cd backend/ - - Set up the environment using the `requirements.txt`: - - cd heritage_graph/ - python manage.py runserver - - - **Data Distribution (Drupal-DKAN)**: - If you are familiar with Drupal or have experience with data distribution systems, you can help manage and improve our DKAN integration. - - - **Knowledge Graphs**: - Help us expand the Knowledge Graphs by contributing to data modeling, improving the graph structure, or integrating new datasets. This section includes the LinkML code. - - - - git clone -b linkML-dev https://github.com/CAIRNepal/CHLOD.git - - Recreate the environment using `requirements.txt`. - - You can now contribute to the Knowledge Graphs section. - -**Write Tests** - It’s essential to write tests for your code to ensure that the platform remains stable and reliable. This is particularly important in the backend and data distribution parts of the project. - -**Submit a Pull Request** - Once you’ve made your changes, push them to your fork and open a pull request (PR) to the **main repository**. Be sure to describe the changes you made in the PR description. - - We review all pull requests carefully and work with you to ensure your contributions are in line with the project’s goals and standards. - -Guidelines for Contributing ---------------------------- - -To make the contribution process smooth and efficient, we have a few guidelines: - -- **Commit Messages**: - Write clear, concise, and meaningful commit messages that describe what and why changes were made. - -- **Issues**: - If you find a bug, have an idea for a new feature, or want to improve something, feel free to open an issue on GitHub. We actively track issues and prioritize them based on community feedback. - -- **Documentation**: - If you add new features or make significant changes, please remember to update the documentation accordingly. This will help others understand your contributions and make the platform more accessible. - -Reporting Issues ----------------- - -If you encounter any bugs or issues, please use the **GitHub Issues** feature to report them. Include as much information as possible, such as: - - Steps to reproduce the issue. - - Expected vs. actual behavior. - - Screenshots (if applicable). - - Any error messages you received. - -Join the Conversation ---------------------- - -We encourage open discussions and feedback from all contributors. If you have questions or need help, you can reach out to the community via: - -- **CAIR-Nepal Discord**: A space to ask questions, propose ideas, or discuss project-related topics. Join us here: https://discord.gg/qSwRaWgk - - -License -------- - - - -Conclusion ----------- - -Thank you for considering contributing to **HeritageGraph**! Every contribution, whether it’s a code fix, a new feature, or a suggestion, helps us create a more inclusive and accessible platform for preserving Nepalese cultural heritage. - -We’re excited to see what you bring to the project and look forward to collaborating with you! diff --git a/documentation/index.rst b/documentation/index.rst deleted file mode 100644 index 087413f38..000000000 --- a/documentation/index.rst +++ /dev/null @@ -1,53 +0,0 @@ -HeritageGraph Documentation -=========================== - -Welcome to the official documentation for **HeritageGraph**, Nepal's first Cultural Heritage Platform! Our goal is to preserve and share the rich cultural heritage of Nepal through innovative digital solutions. With **HeritageGraph**, we are digitizing cultural heritage data using Knowledge Graphs (KGs), making it more accessible, sustainable, and ready for the digital age. - -What is HeritageGraph? ----------------------- - -**HeritageGraph** is a platform that creates a digital representation of Nepal’s cultural heritage. By converting physical artifacts, documents, and traditions into digital formats, we are ensuring their preservation, accessibility, and future relevance. In today’s world, digitalization is key to safeguarding cultural heritage from physical decay and loss. It also opens up new avenues for education, research, and cross-cultural exchange, making heritage more accessible to everyone. - -Cultural heritage holds the memories, stories, and wisdom of humanity. By preserving it digitally, we not only protect our shared past but also ensure that future generations can reconnect with it and gain new insights. **HeritageGraph** helps us to achieve this by using Knowledge Graphs. - -Why Digitize Cultural Heritage? ----------------------------------- - -Digitizing cultural heritage is essential for a number of reasons: - -- **Preservation**: Protecting valuable cultural artifacts and traditions from physical degradation and loss. -- **Accessibility**: Making cultural heritage accessible to a wider audience, from students to researchers. -- **Education**: Enabling better learning and understanding of cultural histories. -- **Research**: Allowing interdisciplinary collaboration to gain new insights into our past. -- **Innovation**: Providing opportunities for new ways to study and present heritage. - -By digitizing cultural heritage, we are creating a connection between the past, present, and future, ensuring that our shared legacy is never forgotten and remains available for future generations. - -About the Project ------------------ - -In this project, we focus on building a machine-readable, yet human-understandable, knowledge graph of Nepalese cultural heritage. By doing so, we aim to give people new ways to interact with, learn from, and explore the wealth of cultural knowledge Nepal has to offer. - -Table of Contents ------------------ - -.. toctree:: - :maxdepth: 3 - :caption: Contents: - - introduction.rst - contributing.rst - - - -Getting Started ---------------- - -To get started with **HeritageGraph**, you can explore the following sections: - -- -- -- -- - -We hope this documentation helps you understand the vision behind **HeritageGraph** and how you can explore, contribute to, and learn from Nepal’s cultural heritage in a new and meaningful way. \ No newline at end of file diff --git a/documentation/introduction.rst b/documentation/introduction.rst deleted file mode 100644 index 5636582fe..000000000 --- a/documentation/introduction.rst +++ /dev/null @@ -1,6 +0,0 @@ -Overview of Knowledge Graphs -============================ - -A **Knowledge Graph (KG)** is a structured representation of data where entities (such as people, places, things, or events) are connected by relationships. These graphs represent complex information in a way that is both machine-readable and understandable by humans. - -In **HeritageGraph**, we use Knowledge Graphs to represent the intricate relationships within Nepalese cultural heritage, such as historical events, locations, and individuals. diff --git a/documentation/make.bat b/documentation/make.bat deleted file mode 100644 index 64d7367a5..000000000 --- a/documentation/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=. -set BUILDDIR= docs - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/documentation/my_module.rst b/documentation/my_module.rst deleted file mode 100644 index e69de29bb..000000000 diff --git a/documentation/requirements.txt b/documentation/requirements.txt deleted file mode 100644 index 91316da6bf26362c97dee480ca0e82df16fff429..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1086 zcmbW0+fKq@5QO*I#7Du{Vu&}sfQg9-Pf!Z9U^%tm>EYFHb}4PtU}DHm+V0Nm?Ck!Z zADLB_*@V;B-ey+Y9lyk`?Ap(zU3hdttnygO_ryl0Xzr-JEo{yaIt82B4H>tbA#Y;I zt)xm#of(w|wzds#E523W-cPlMV1#W^8{*2$JXicuri_vEPKoArfOA1+;|i3KdKanZ zENn`>%wytDj_eEPEU4WaHMHG}KXL3mk+m&Br#-wBsH+FQ*Y-sHt&Mq}!zB(?2^GrP z63NNRtZ=r%bHbxg_-Jp$R-o5(5?zGT@-V!piSDQ*wf&qS%H*>uHSX(+&#ZDkG}VADlbNDI9=YL{LbgZZ?<^9UB>ET@0>v!eLqwh6SlICtZ&goq;4ehu5YWGSz5qotG xxjTB?S1RP+9_e<;@Ag({cMIxA_dosKGb8!Z-rSge)H%SU9n$oMr&)Eo_5}tLsVV>f