Writing guide 

Table of Contents

Writing guide

Note: see this document online in https://docs.pjsip.org/en/latest/specific-guides/other/writing-guide.html

Heading convention 

====================
H0 (for site title)
====================

H1 (prefer this for document title)
===================================


We also use this for document title:

Also H1 and document title
*********************************

(Historically, *** is higher level than === in this site, but then the layer
with *** was deleted, so === becomes H1)


H2
------------------------

H3
~~~~~~~~~~~~~~~~~~~~~~~~~

Also H3
^^^^^^^^^^^^^^^^^^^^^^^^^

(I prefer ~~~ for H3 since it's less conspicuous)

H4
``````````````

Typography conventions 

For PJSIP symbols, use breathe-apidoc constructs, e.g.:
- Special for macros, use :c:macro:`MACRO` construct:
  - PJLIB: :c:macro:`PJ_HAS_TCP` –> PJ_HAS_TCP
  - PJLIB-UTIL: :c:macro:`PJ_DNS_RESOLVER_MAX_TTL` –> PJ_DNS_RESOLVER_MAX_TTL
  - PJNATH: :c:macro:`PJ_STUN_MAX_PKT_LEN` –> PJ_STUN_MAX_PKT_LEN
  - PJMEDIA: :c:macro:`PJMEDIA_CONF_USE_AGC` –> PJMEDIA_CONF_USE_AGC
  - PJSIP: :c:macro:`PJSIP_MAX_URL_SIZE` –> PJSIP_MAX_URL_SIZE
- For everything else, use :cpp:any:`SYMBOL` construct:
  C API: :cpp:any:`pjsua_handle_ip_change()` –> pjsua_handle_ip_change()
  
  C struct: :cpp:any:`pjsua_ip_change_param` –> pjsua_ip_change_param
  
  C field: :cpp:any:`pjsua_callback::on_call_state` –> pjsua_callback::on_call_state
  
  PJSUA2 class: :cpp:any:`pj::AccountConfig` –> pj::AccountConfig
  
  PJSUA2 method: :cpp:any:`pj::Account::create()` –> pj::Account::create()
For other identifier: identifier
command
file name
Bold for UI items like OK button, File -> Open menu, and for normal emphasis like this is important.
Italics for quoted info, e.g. according to RFC 123 Section 1.2: Open source software is good.

Note

Sometimes macros wouldn’t resolve, e.g. PJ_HAS_TCP. Many PJLIB macros won’t resolve. Could it be because some macros are declared in CFLAGS by configure (so they are not picked up by Doxygen)?
nested struct member wouldn’t resolve, e.g.: pjsua_acc_config::ip_change_cfg::hangup_calls, so you need to break it down into separate parts, e.g. hangup_calls of pjsua_acc_config::ip_change_cfg
For full reference see https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cpp-domain

Cross referencing 

Tip

Rather than explicitly specifying the role in the link (with :doc: or :ref:), you can use :any: to make Sphinx automatically detect the best role to use for the specified target.

Linking to documentation section

Links to sections in the menu:

PJSIP Overview
Get Started
PJSUA2 Guide
Specific Guides
API Reference & Samples: API Reference & Samples

Linking to a page

Use :any: or :doc: to link to a page.

Sample linking to getting started pages:

Sample linking to root API reference pages and samples:

Linking to doxygen group/topic

To link to specific doxygen group/topic:

Open the relevant API reference page (e.g. API Reference)
View the source to get the link, e.g.
```
`:doc:`uPnP </api/generated/pjnath/group/group__PJNATH__UPNP>`
```
which will be rendered as uPnP

Available cross-references:

Currenty available cross-references:

$ egrep -r '^.. _' * | grep rst
api/pjlib/index.rst:.. _pjlib_pool:
api/pjlib/index.rst:.. _pjlib_string:
api/pjnath/ref.rst:.. _ice:
api/pjnath/ref.rst:.. _stun:
api/pjnath/ref.rst:.. _turn:
api/pjnath/ref.rst:.. _upnp:
api/pjnath/ref.rst:.. _nat_detect:
api/pjmedia/pjmedia-audiodev.rst:.. _audiodev_supported_devs:
api/pjmedia/pjmedia-audiodev.rst:.. _alsa:
api/pjmedia/pjmedia-audiodev.rst:.. _opensl:
api/pjmedia/pjmedia-audiodev.rst:.. _jnisound:
api/pjmedia/pjmedia-audiodev.rst:.. _oboe:
api/pjmedia/pjmedia-audiodev.rst:.. _bdsound:
api/pjmedia/pjmedia-audiodev.rst:.. _coreaudio:
api/pjmedia/pjmedia-audiodev.rst:.. _wmme:
api/pjmedia/pjmedia-audiodev.rst:.. _wasapi:
api/pjmedia/pjmedia-audiodev.rst:.. _portaudio:
api/pjmedia/pjmedia-videodev.rst:.. _android_cam:
api/pjmedia/pjmedia-videodev.rst:.. _avi_device:
api/pjmedia/pjmedia-videodev.rst:.. _avfoundation:
api/pjmedia/pjmedia-videodev.rst:.. _colorbar:
api/pjmedia/pjmedia-videodev.rst:.. _dshow:
api/pjmedia/pjmedia-videodev.rst:.. _ffmpeg_capture:
api/pjmedia/pjmedia-videodev.rst:.. _opengl:
api/pjmedia/pjmedia-videodev.rst:.. _qtdev:
api/pjmedia/pjmedia-videodev.rst:.. _sdl:
api/pjmedia/pjmedia-videodev.rst:.. _guide_sdl:
api/pjmedia/pjmedia-videodev.rst:.. _video4linux:
api/pjmedia/pjmedia-videodev.rst:.. _guide_video4linux:
api/pjmedia/pjmedia-codec.rst:.. _pjmedia-codec:
api/pjmedia/pjmedia-codec.rst:.. _amediacodec:
api/pjmedia/pjmedia-codec.rst:.. _bcg729:
api/pjmedia/pjmedia-codec.rst:.. _ffmpeg:
api/pjmedia/pjmedia-codec.rst:.. _g711:
api/pjmedia/pjmedia-codec.rst:.. _g722:
api/pjmedia/pjmedia-codec.rst:.. _g7221:
api/pjmedia/pjmedia-codec.rst:.. _gsm:
api/pjmedia/pjmedia-codec.rst:.. _ilbc:
api/pjmedia/pjmedia-codec.rst:.. _ipp:
api/pjmedia/pjmedia-codec.rst:.. _l16:
api/pjmedia/pjmedia-codec.rst:.. _opencore_amr:
api/pjmedia/pjmedia-codec.rst:.. _openh264:
api/pjmedia/pjmedia-codec.rst:.. _opus:
api/pjmedia/pjmedia-codec.rst:.. _passthrough:
api/pjmedia/pjmedia-codec.rst:.. _silk:
api/pjmedia/pjmedia-codec.rst:.. _speex:
api/pjmedia/pjmedia-codec.rst:.. _libvpx:
get-started/android/build_instructions.rst:.. _android_pjsua2:
get-started/android/build_instructions.rst:.. _android_create_app:
get-started/ios/issues.rst:.. _ios_bg:
get-started/guidelines-development.rst:.. _dev_start:
get-started/guidelines-development.rst:.. _config_site.h:
get-started/guidelines-api.rst:.. _which_api_to_use:
overview/license_3rd_party.rst:.. _licensing_3rd_party:
pjsua2/using/call.rst:.. _pjsua2_call_disconnection:
pjsua2/using/account.rst:.. _pjsua2_creating_userless_account:
specific-guides/sip/index.rst:.. _guide_adding_custom_header:
specific-guides/build_int/ffmpeg.rst:.. _guide_ffmpeg:
specific-guides/audio/webrtc.rst:.. _guide_webrtc:
specific-guides/audio/opencore-amr.rst:.. _guide_opencore_amr:
specific-guides/audio/index.rst:.. _guide_ipp:
specific-guides/perf_footprint/index.rst:.. _guide_performance:
specific-guides/perf_footprint/index.rst:.. _guide_footprint:
specific-guides/security/ssl.rst:.. _guide_ssl:
specific-guides/network_nat/qos.rst:.. _qos:
specific-guides/other/writing-guide.rst:.. _my_secret_target:
specific-guides/video/index.rst:.. _guide_libyuv:
specific-guides/video/index.rst:.. _guide_vidconf:

Creating own cross reference

This is if you want to create and cross reference a specific location in a page (rather than the whole page).

First create the link target (analogous to <A name>). Don’t forget the underscore before the id:

.. _my_secret_target:

Then to reference the target, use my_secret_target or With a text (note: there’s no underscore).

See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role for more info.

Linking to GitHub

Issue #1234
PR #3291
source pjmedia/include/pjmedia/config.h
source directory pjmedia/include

Note

In practice :issue: or :pr: can be used interchangeably since GitHub will redirect to correct URL, but it’s best to use the correct construct to avoid unnecessary redirect.

RFC link

Use :rfc:\`3711\` which will be rendered as RFC 3711.

External links

E.g. PJSIP website

Note: use double instead of single underscore.

Linking from external website 

Find the target link from the front page: https://docs.pjsip.org/en/latest/index.html

Notes, Warnings, and Blocks 

Note

This is a note

Tip

This is a tip

Warning

This is a warning

/* Sample C code */
puts("Hello world");

$ echo Hello world

References:

Local TOC 

It’s recommended to have TOC at the start of the document:

.. contents:: Table of Contents
    :depth: 2

Converting from Trac wiki 

This is what I found to get the best conversion result, although bear in mind that the best result still requires a lot of manual editing afterwards. It requires Pandoc though (https://pandoc.org/).

Download Trac wiki page to a temporary file
Convert:

$ trac2down tracwikifile.trac | pandoc -f markdown -t rst > output.rst

Note: trac2down.py is in the root dir of pjproject_docs

Note: there should be other tools to convert from markdown to rst. I happen to have Pandoc installed.