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.
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.
\ No newline at end of file
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