README content. pjproject version 2.9

README.md

@@ -2,7 +2,17 @@
 
 ## Overview
 
-This repository contains source and configuration files to generate https://pjsip.readthedocs.io site.
+### Overview of The Documentation Infrastructure
+
+The PJSIP docs at **https://docs.pjsip.org** is hosted by the *Read the Docs* (RTD) service. It contains:
+1. reference manuals (was at [pjsip.org/docs/latest/...](https://www.pjsip.org/docs/latest/pjlib/docs/html/index.htm)
+2. pjsua2 book (was at [pjsip.org/docs/book-latest](https://www.pjsip.org/docs/book-latest/html/index.html))
+3. (TODO) wiki (previously at https://trac.pjsip.org/repos/) 
+
+The PJSIP's RTD settings page is at https://readthedocs.org/projects/pjsip/. Here you can control various aspects of the RTD page.
+
+The documentation repository is at https://github.com/pjsip/pjproject_docs (you're reading the README of that repository).
+
 
 ### Directory Layout
 
@@ -21,13 +31,11 @@ This repository contains source and configuration files to generate https://pjsi
 
 ### Overview of Generation Process
 
-1. The `pjproject` submodule in `docs/source/pjproject` needs to be updated
-   to the correct version using `git pull` in that directory. In RTD build server, this is done automatically.
-2. When running Sphinx's `make doc`, or when building the doc in RTD server, the following happen:
-    * doxygen is run by `conf.py`. This outputs XML files in various `pjproject/**/docs` directories.
-    * `breathe-apidoc` is run by `conf.py`. This script reads Doxygen's XML files and outputs
-      `.rst` documentation for all files in `docs/source/api/generated` directory.
-    * Sphinx then processes the `.rst` files and build a nice documentation.
+There are two ways to build PJSIP RTD docs: locally, and in the RTD server. You build the docs locally only when developing the documentation itself, i.e. to preview the docs locally. 
+
+For the live version, the docs are built in the RTD server, either triggered manually from the RTD settings page (above), or automatically every time someone commits **to the pjproject_docs repository** (i.e., not to the main *pjproject* repository!).
+
+More will be explained in *Generating Documentation* section below.
 
 ## Installation
 
@@ -54,26 +62,29 @@ $ sphinx-build --version
 $ breathe-apidoc --version
 ```
 
-## Generating Documentation
+## Generating Documentation Locally
+
+You build docs locally when you modify the docs (such as releasing new version, modifying
+the content) in order to test it locally first before updating the live docs. 
 
-These are the instructions for generating the documentation locally.
+Here are the steps to do it. Make sure you have followed the steps in *Installation* above.
 
 ### Pull pjproject source
 
-There is a pjproject submodule in `docs/source/pjproject` directory. 
-Pull this pjproject submodule according to the version which documentation is to be built.
-E.g. if you're building the latest docs, then you can just pull the latest source.
-Otherwise pull the relevant version.
+There is a `pjproject` submodule in `docs/source/pjproject` directory.
 
-You may also need to checkout to different branch than the master. This is totally
-up to you. 
+The first time after you clone `pjproject_docs`, you need to pull the submodules with
+the following command in the `pjproject_docs` directory:
 
 ```sh
-$ cd docs/source/pjproject
-$ git pull
-$ git checkout pjsip_docs
+$ git submodule update --init --recursive
 ```
 
+Subsequently, use this when updating `pjproject_docs` to pull the submodules:
+
+```sh
+$ git pull --recurse-submodules
+```
 
 ### Generate the Docs
 
@@ -101,7 +112,29 @@ $ cd docs
 $ make html
 ```
 
-The result is `docs/build/html/index.html`. 
+The result is `docs/build/html/index.html`. You can previous the result in the browser.
+
+#### Notes
+
+Just for information, when running Sphinx's `make html`, or when building the doc in RTD server, the following processes happen:
+* doxygen is run by `conf.py`. This outputs XML files in various `pjproject/**/docs` directories.
+* `breathe-apidoc` is run by `conf.py`. This script reads Doxygen's XML files and outputs
+  `.rst` documentation for all files in `docs/source/api/generated` directory.
+* Sphinx then processes the `.rst` files and build a nice documentation.
+
+
+## Generating Live Documentation
+
+The live (RTD) docs in https://docs.pjsip.org are generated automatically when someone commits
+anything to the `pjproject_docs` repository. Alternatively, you can manually trigger rebuilding
+of the doc from the PJSIP's RTD settings page. 
+
+## Releasing New Version
+
+First read how versioning is done in RTD: https://docs.readthedocs.io/en/stable/versions.html
+
+
+
 
 ## Guides