{"id":23231516,"url":"https://github.com/pjsip/pjproject_docs","last_synced_at":"2025-08-19T16:33:48.491Z","repository":{"id":45696099,"uuid":"242652722","full_name":"pjsip/pjproject_docs","owner":"pjsip","description":"Source and configuration files for https://docs.pjsip.org","archived":false,"fork":false,"pushed_at":"2024-12-16T05:41:45.000Z","size":5506,"stargazers_count":9,"open_issues_count":2,"forks_count":15,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-12-16T06:28:43.821Z","etag":null,"topics":["pjsip"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pjsip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-24T05:18:53.000Z","updated_at":"2024-12-16T05:41:48.000Z","dependencies_parsed_at":"2024-08-08T12:16:04.225Z","dependency_job_id":"2319266c-a12d-490c-a47e-993e248013ee","html_url":"https://github.com/pjsip/pjproject_docs","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjsip%2Fpjproject_docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjsip%2Fpjproject_docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjsip%2Fpjproject_docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pjsip%2Fpjproject_docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pjsip","download_url":"https://codeload.github.com/pjsip/pjproject_docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230363932,"owners_count":18214717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pjsip"],"created_at":"2024-12-19T02:15:01.842Z","updated_at":"2025-08-19T16:33:48.471Z","avatar_url":"https://github.com/pjsip.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docs.pjsip.org Project\n\n[![docs.pjsip.org](https://readthedocs.org/projects/pjsip/badge/?version=latest)](https://docs.pjsip.org/en/latest/)\n\n(Note: see also [writing-guide.rst](docs/source/specific-guides/other/writing-guide.rst))\n\n## Overview\n\n### Overview of the documentation infrastructure\n\nThe PJSIP docs at **https://docs.pjsip.org** is hosted by the *Read the Docs* (RTD) service. It contains:\n1. reference manuals (was at [pjsip.org/docs/latest/...](https://www.pjsip.org/docs/latest/pjlib/docs/html/index.htm)\n2. pjsua2 book (was at [pjsip.org/docs/book-latest](https://www.pjsip.org/docs/book-latest/html/index.html))\n3. wiki (previously at https://trac.pjsip.org/repos/) \n\nThe PJSIP's RTD settings page is at https://readthedocs.org/projects/pjsip/. This page controls various aspects of the RTD page. Some will be explained below.\n\nThe documentation repository is at https://github.com/pjsip/pjproject_docs. You are reading the README\nof that repository.\n\n\n### Contents\n\n- `docs/`\n    - `source/`\n        - `conf.py`: Sphinx conf\n        - `*.rst`: hand-written documentation\n        - `pjproject/`: Git submodule for pjproject\n        - `api/`\n            - `*.rst`: hand-written index files for API reference\n            - `generated/`: output directory of `breathe-apidoc`\n        - `pjsua2/`\n            - `*.rst`: PJSUA2 book (was pjsip-book)\n    - `build/`: output files will be placed here\n- `readthedocs.yml`: configuration for generating live RTD.\n- `requirements.txt`: Python modules required to build the docs\n- `Dockerfile`: to build Docker image.\n\n\n### Overview of the generation process\n\nThere are three methods to build PJSIP RTD docs: \n1. In the RTD server. This method is the simplest, and it's intended for routine operations such as\n   releasing new version or minor editing of the documentation.\n2. (locally) using provided Docker image. This is the preferred method for authoring/developing the\n   documentation.\n3. (locally) using manual installation, if you don't want to use the Docker image, or if you need\n   to understand how the Docker image is built.\n\n\n## Method 1: managing live documentation\n\nUse this method to perform routine tasks such as releasing new PJSIP version or editing of the documentation.\n\nThis method doesn't require any software except git and text editor. In fact, you don't even need those as you can edit the files directly on GitHub (but this is not recommended).\n\nThe live (RTD) docs in https://docs.pjsip.org are generated automatically whenever changes are pushed to the `pjproject_docs` repository (note: not the *pjproject* repository!). So remember that every commit will trigger costly build in RTD.\n\nYou can see the live building process, as well as logs of all previous build processes from the **Builds** page (https://readthedocs.org/projects/pjsip/builds/). This comes handy when the build failed to investigate what went wrong.\n\nYou can also manually trigger rebuilding of the doc by clicking **Build Version** from that page, but this shouldn't be necessary unless you modify something in the RTD settings and want to regenerate the docs.\n\n### Editing documentation\n\nJust pull *pjproject_docs* to your computer, edit, commit, and push the files. Once the files are pushed to GitHub, this will trigger a build process in RTD.\n\nNote: \n\n- consider creating a branch when editing the docs, especially if the edit is not very trivial, to avoid excessive builds in RTD server.\n\n### Creating new documentation version for a new PJSIP release\n\nFollow the instructions in [Versioning the documentation](#versioning-the-documentation) section below.\n\n## Method 2: Using the Docker image\n\nWe've provided an Ubuntu 22.04 Docker image that contains all the required software to develop the\ndocs. It is equipped with two nice editors, **vim** and **tilde**, and it even contains pre-built\ndocumentation to get you started.\n\nBelow are steps to use this method.\n\n### Install Docker\n\nFollow the installation instructions on https://www.docker.com/get-started/ to install Docker on\nyour system (Linux, Mac, or Windows).\n\n### Pull and run pjproject-docs image\n\n```\n$ docker pull pjsip/pjproject-docs\n$ docker run -dit -p 8000:8000 --name=pjproject-docs pjsip/pjproject-docs\n```\n\n### Viewing local RTD\n\nPoint your browser to http://localhost:8000 to view RTD served by the Docker container.\n\n### Open terminal to the Docker container\n\n```\n$ docker exec -it pjproject-docs bash\n```\n\nThe next section explains how to edit and generate the docs.\n\n### Editing the docs\n\n(In the Docker container terminal)\n\n1. Go to `/root/pjproject_docs` directory to edit the files, rebuild the documentation etc. \n   as explained in the next section (**Generating Documentation Locally**)\n   - Note: The container contains two nice text editors: **vim** and **tilde**. \n     You may of course install other editors (or any other software, for that matter) \n     using `apt-get install` as usual.\n2. The HTTP server is served by `python3 -m http.server` background process. It automatically\n   serves the latest generated HTML files in `docs/build/html` directory.\n\n\n## Generating documentation locally\n\nThe Docker container already contains cloned repository of the `pjproject-docs` in\n`/root/pjproject-docs`. You can pull, add, edit, modify, and push this repository as usual.\n\nBelow are steps to generate the docs. Perform these steps in the Docker container terminal.\n\n### Git pull\n\n```sh\n$ cd pjproject_docs\n$ git pull --recurse-submodules\n$ git submodule update --remote\n```\n\nNote:\n\n- if directory `source/pjproject` is still empty, run:\n\n```\n$ git submodule update --init --recursive\n```\n\n### Update requirements\n\nNew Python modules may be added to requirements after the docker image is created, so let's\nmake sure all required Python modules are installed.\n\n```cmd\n$ pip install -r requirements.txt\n```\n\n### Generate the docs\n\n#### 1. Set environment variable\n\nThe `READTHEDOCS` environment variable is used to control whether Doxygen XML and *breathe*\nAPI docs needs to be regenerated. You need to set it to generate docs for different PJPROJECT\nversions. On the other hand, when you only edit the `.rst` files, there is no need to regenerate\nthe Doxygen files, so unset it (`unset READTHEDOCS`). \n\nTo set the value:\n```\n$ export READTHEDOCS=True\n``` \n\n\n#### 2. Build the docs\n\n```sh\n$ cd docs\n$ make clean html\n```\n\nThe result is `docs/build/html/index.html`. Now refresh the http://localhost:8000 page in the host\ncomputer to view the updated docs.\n\n## How it works\n\nThis section is just for information. \n\nWhen running Sphinx's `make html`, or when building the doc in RTD server, the following processes happen:\n\n* `docs/source/conf.py` is read by sphinx\n* if `READTHEDOCS` environment variable is set to True, `doxygen` is run by `conf.py`. This outputs Doxygen XML files in various `pjproject/**/docs` directories.\n* `breathe-apidoc` is run by `conf.py`. This script reads Doxygen's XML files and outputs\n  `.rst` documentation for all files in `docs/source/api/generated` directory.\n* Sphinx then processes the `.rst` files and build a nice documentation.\n\n\n## Versioning the documentation\n\nRTD supports multiple versions of the docs. It does so by analyzing the Git *tags* of the **pjproject_docs** repository.\n\nBy default, RTD only supports `latest` version of the doc, which corresponds to latest commit in Git `master` (again, of the `pjproject_docs` repository). If you wish to show the individual version, activate the version from https://readthedocs.org/projects/pjsip/versions/.\n\nFor more info please see https://docs.readthedocs.io/en/stable/versions.html\n\nFollow the steps below to create documentation for specific PJSIP version.\n\n### Creating new documentation version\n\n#### 1a: get the source\n\nPull the docs:\n\n```sh\n$ cd pjproject_docs\n$ git pull\n```\n\n#### 1b: get the source (for Docker installation)\n\nOpen terminal to the Docker container\n\n```\n$ docker exec -it pjproject-docs bash\n```\n\nAll the remaining steps are done in the the terminal to the Docker container.\n\nPull the docs:\n\n```sh\n$ cd pjproject_docs\n$ git pull --recurse-submodules\n$ git submodule update --remote\n```\n\nNote:\n\n- if directory `source/pjproject` is still empty, run:\n\n```\n$ git submodule update --init --recursive\n```\n\nSet READTHEDOCS environment variable:\n\nBash:\n```\n$ export READTHEDOCS=True\n``` \n\n#### 2. Set which PJPROJECT version to build\n\n1. Edit `docs/source/conf.py` (note: use **tilde** or **vim**)\n2. Modify **`pjproject_tag`** to match the PJPROJECT Git **tag** which documentation is to be built. Example:\n   ```python\n   pjproject_tag = '2.10'\n   ``` \n3. Save and close\n\n\n#### 3. Optional: build the docs locally\n\nYou need to have local installation to do this. Build the docs by running these:\n\n```sh\n$ cd docs\n$ make clean html\n```\n\nThen open `docs/build/html/index.html` to preview the result.\n\n#### 4. Git commit (but don't push yet)\n\n```sh\n$ cd pjproject_docs\n$ git add -u\n$ git commit -m 'Setting pjproject version to 2.10'\n```\n\n\n#### 5. Tag pjproject_docs\n\n```sh\n$ git tag 2.10\n```\n\n#### 6. Git push with tags\n\nPush the tags first then the code.\n\n```sh\n$ cd pjproject_docs\n$ git push --tags\n$ git push\n```\n\nThe last command would trigger a building process for version `latest` in RTD. \n\n#### 7. See the building process\n\nOpen https://readthedocs.org/projects/pjsip/builds/, there should be one that is currently \nbuilding (i.e. for `latest` version).\n\nYou may wait until it is finished (it will take approximately 15 minutes) to make sure that \neverything is okay, or otherwise continue to the next steps (but it will cause more than one \nbuild processes to be started by RTD, which is okay).\n\n#### 8. Activate the version\n\nGo to https://readthedocs.org/projects/pjsip/versions/, and activate the new version and make it active and public.\n\nThis will trigger a new build process for that version.\n\n#### 9. Wait the build process\n\nWait until all build processes are finished.\n\n\n### Restoring documentation for latest master\n\nAfter a version is released, if you want to generate a documentation for the latest *master*\n(i.e. before next version is released), you need to do the following.\n\n#### 1. Set PJPROJECT version to *master*\n\n1. Edit `docs/source/conf.py`\n2. Set **`pjproject_tag`** `master`, e.g.:\n    ```python\n   pjproject_tag = 'master'\n   ``` \n3. Save and close\n\n#### 2. Commit and Push\n\n```sh\n$ cd pjproject_docs\n$ git add -u\n$ git commit -m ..\n$ git push\n```\n\nNote that **you must not add any tags** to the `pjproject_docs` repository.\n\n#### 3. Watch the building process\n\nThere should be a build process for the *latest* version.\n\n\n### Handling errors\n\nIf the building fails, these are the steps to recreate the documentation.\n\n1. Investigate the error by looking at the build logs (in the Builds page)\n2. Fix the error.\n3. If the error is in the `latest` version, you just need to commit, push, and watch the building process in RTD.\n4. If the error is in the tagged version (e.g. `2.10`, etc.), then you need to delete the tag first:\n\n   ```sh\n   $ git tag -d \u003cthe tag\u003e\n   $ git push --delete origin \u003cthe tag\u003e\n   ``` \n\n\n### (Only for local installation) Cleaning generated files\n\nTo clean up the `build` directory:\n\n```\n$ cd docs\n$ make clean\n```\n\n## Method 3: Manual installation\n\nThese are for generating the docs locally if you do not wish to use the Docker image\n(note for RTD, the required installations are already specified in `readthedocs.yml`\nand `requirements.txt`). \n\nNote that local installation is not required for releasing new documentation version (new pjproject version). You only need a text editor for that.\n\nAlso note that these are only tested on Linux at the moment, and Windows will not work\n(because `conf.py` calls `./configure` to initialize the macros). Mac may work but untested.\n\n\n#### 1. Install Doxygen 1.8.4\n\nYou need at least Doxygen 1.8.1 because Doxygen 1.5.1 is not suitable for Breathe.\n\n#### 2. Install Python\n\nWe need Python version 3.7 or newer. It's also recommended to create `virtualenv` environment to avoid cluttering your main Python installation.\n\n#### 3. Clone pjproject_docs with the submodules\n\n```sh\n$ git clone https://github.com/pjsip/pjproject_docs.git\n$ cd pjproject_docs\n$ git submodule update --init --recursive\n```\n\nNote: the last command is for fetching the `pjproject` submodule in `docs/source/pjproject` directory.\n\n#### 4. Install other requirements\n\nRun this command (maybe inside your virtualenv) to install the required Python modules:\n\n```cmd\n$ pip install -r requirements.txt\n```\n\n\n#### 5. Check installation\n\nCheck that the tools are available on the PATH by running the following:\n\n```\n$ doxygen -v\n$ sphinx-build --version\n$ breathe-apidoc --version\n```\n\nBelow are the versions in my installations, just for reference:\n\n```\n1.9.1\nsphinx-build 5.1.0\nBreathe (breathe-apidoc) 4.34.0\n```\n\n#### 6. Generate documentation locally\n\nFollow instructions in [Generating documentation locally](#generating-documentation-locally)\n\n#### 7. Serving the documentation\n\n```sh\n$ cd docs/build/html\n$ python -m http.server\n```\n\nAnd then open http://localhost:8000/docs/build/html\n\n\n## Generating Docker image\n\n### Install requirements\n\nInstall the required software as explained in **Manual Installation** section above.\n\n### Fetch and generate documentation locally\n\nFollow the instructions in **Generate the Docs** section above.\nThe objective is to copy this generated documentation to the Docker image file\nso that the image doesn't have to start from scratch.\n\n\n### Build the Docker image\n\n```\n$ cd pjproject_docs\n$ docker build --tag pjproject-docs .\n```\n\n### Test the image\n\nRun a Docker container from the image with `docker run` (see above).\n\n### Tag and upload the image\n\nThis is for PJSIP team to upload the image to Docker hub repository:\n\n```\n$ docker tag pjproject-docs pjsip/pjproject-docs\n$ docker login\n$ docker push pjsip/pjproject-docs\n```\n\n## Cheatsheet\n\nImage related commands:\n\n```\ndocker build --tag pjproject-docs .\ndocker image ls\ndocker image rm pjproject-docs\n```\n\nContainer related commands:\n\n```\ndocker run -dit -p 8000:8000 --name=pjproject-docs pjsip/pjproject-docs\ndocker ps\ndocker container ls\ndocker exec -it pjproject-docs bash\ndocker kill pjproject-docs\ndocker start pjproject-docs\ndocker container rm pjproject-docs\n```\n\nRepository related commands:\n\n```\ndocker tag pjproject-docs pjsip/pjproject-docs\ndocker push pjsip/pjproject-docs\n```\n\nService commands:\n\n```\nsudo service docker start\nsudo systemctl start docker.socket\n```\n\n## More Info\n\nFor reference:\n\n- https://docs.readthedocs.io/en/stable/index.html\n- http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html\n- https://breathe.readthedocs.io/en/latest/index.html\n- https://breathe.readthedocs.io/en/latest/readthedocs.html\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjsip%2Fpjproject_docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpjsip%2Fpjproject_docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpjsip%2Fpjproject_docs/lists"}