From 4f9f05f4feb3e83d80f9d874530421135b4fcc07 Mon Sep 17 00:00:00 2001 From: lintao <lintao@ihep.ac.cn> Date: Sun, 20 Oct 2024 11:12:56 +0800 Subject: [PATCH] Doc: add instruction to build doc. --- docs/source/development/doc.md | 33 +++++++++++++++++++++++++++++ docs/source/development/overview.md | 16 +++++++++++++- docs/source/index.rst | 1 + 3 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 docs/source/development/doc.md diff --git a/docs/source/development/doc.md b/docs/source/development/doc.md new file mode 100644 index 00000000..b17bc7a4 --- /dev/null +++ b/docs/source/development/doc.md @@ -0,0 +1,33 @@ +# How to contibute to Documentation + +The CEPCSW user guide is created using a tool called sphinx. Sphinx could parse the Markdown files and then create HTML files. The Markdown files are all maintained in the source code of CEPCSW. + +Here is an instruction to add or modify the user guide: +* Fork the CEPCSW and git clone the source code +```bash +$ git clone git@code.ihep.ac.cn:cepc/CEPCSW.git +$ cd CEPCSW/docs/ +``` +* Add or modify the markdown files + * If you need to add new pages, please add file names in the index.rst. +* If sphinx is not available, you need to install it and its dependencies. See the below instructions. +```bash +$ python -m venv venv # create a virtual environment +$ source venv/bin/activate # activate the venv +$ pip install -r requirements.txt # install the dependencies +``` +* Build the user guide with sphinx +```bash +$ make html +``` +* Run a lightweight web server using python. + * The URL will consists of two parts: server name and port number. + * Use the command `hostname` to get the name of the server name. If you build the docs in your local computer, just use `localhost`. + * If the port number `8888` is already used by others, just change to some other number. + +```bash +$ python -m http.server 8888 --bind 0.0.0.0 --directory build/html +``` +* Use Web Browser to view the document. + * For example: http://localhost:8888 +* If there is no issue, then `git commit` and `git push`. Create a MR when it is ready. diff --git a/docs/source/development/overview.md b/docs/source/development/overview.md index dc7dd54c..883e2fa6 100644 --- a/docs/source/development/overview.md +++ b/docs/source/development/overview.md @@ -1,3 +1,17 @@ # Development Process Overview -Under construction. \ No newline at end of file +Modern HEP experiments (usually long timescale) are large distributed collaborations with several hundred people. The software project should be managed properly and the code quality is important. + +Software development life cycle consists of +* Planning +* Analysis and Design +* Implementation +* Testing and Integration +* Maintenance + +Best Practices in the open source communities: +* Building software -> CMake +* Source code control -> Git and Pull/Merge Request workflow +* Continuous integration -> GitHub Actions or GitLab CI +* Software distribution -> package management tools and apptainer containers +* Training and documentation -> sphinx diff --git a/docs/source/index.rst b/docs/source/index.rst index 4f1f654f..f737e312 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,6 +23,7 @@ Contents :caption: Development Process development/overview.md + development/doc.md .. toctree:: :maxdepth: 2 -- GitLab