diff --git a/docs/source/development/doc.md b/docs/source/development/doc.md new file mode 100644 index 0000000000000000000000000000000000000000..b17bc7a48cf136ffa6a16482b1daaf66cc0d2eea --- /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 dc7dd54c98e71836492a9ecb211398227a5ce306..883e2fa6570c0b23b48309e7e2f178dee7dcd1a2 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 4f1f654fd291e592178f514132229a65dc8bb485..f737e312ecb6ee6beece9fdb5a2dd645bd817c56 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