diff --git a/g3doc.lua b/g3doc.lua new file mode 100644 index 0000000000..85d8474a12 --- /dev/null +++ b/g3doc.lua @@ -0,0 +1 @@ +return require(this.dirname..'g3doc/g3doc.lua') diff --git a/g3doc/g3doc.lua b/g3doc/g3doc.lua index c6ab1626df..e97289ff81 100644 --- a/g3doc/g3doc.lua +++ b/g3doc/g3doc.lua @@ -1,15 +1,17 @@ return { theme = { - '@builtins/theme/ng.md' + '@builtins/theme/ng.md', -- We don't want to have more than h3 headings in the Table Of Content. - --toc_level = 3, + toc_level = 3, }, site = { name = 'WebRTC C++ library', - home = '/g3doc/index.md', - logo = '/g3doc/logo.svg', - map = '/g3doc/sitemap.md', + home = this.dirname..'index.md', + logo = this.dirname..'logo.svg', + map = this.dirname..'sitemap.md', + -- Ensure absolute links are rewritten correctly. + root = this.dirname..'..' }, visibility = { '/...' }, diff --git a/g3doc/how_to_write_documentation.md b/g3doc/how_to_write_documentation.md index aa0414cf69..6fbca116a5 100644 --- a/g3doc/how_to_write_documentation.md +++ b/g3doc/how_to_write_documentation.md @@ -28,35 +28,44 @@ usage and leave rare ones or side effects for class/function level comments. In the WebRTC repo, conceptual documentation is located in `g3doc` subfolders of related components. To add a new document for the component `Foo` find a `g3doc` subfolder for this component and create a `.md` file there with -desired documentation. If there is no `g3doc` subfolder, create a new one -and add `g3doc.lua` file there with following content: +desired documentation. If there is no `g3doc` subfolder, create a new one; + +When you want to specify a link from one page to another - use the absolute +path: ``` -config = require('/g3doc/g3doc.lua') -return config +[My document](/module/g3doc/my_document.md) ``` If you are a Googler also please specify an owner, who will be responsible for keeping this documentation updated, by adding the next lines at the beginning of your `.md` file immediately after page title: -``` +```markdown ' %?> ' %?> ``` +If you want to configure the owner for all pages under a directory, create a +`g3doc.lua` file in that directory with the content: + +```lua +config = super() +config.freshness.owner = '' +return config +``` + After the document is ready you should add it into `/g3doc/sitemap.md`, so it -will be visible for others. +will be discoverable by others. ### Documentation format -The documentation is written in g3doc, which is a markup format derived from -markdown. This is processed by multiple tools, so we recommend using only simple -markup, and previewing the documents in multiple viewers if possible. +The documentation is written in GitHub Markdown +([spec](https://github.github.com/gfm/#:~:text=GitHub%20Flavored%20Markdown%2C%20often%20shortened,a%20strict%20superset%20of%20CommonMark.)). ## Class/function level comments -Documentation of specific classes and function APIs and their usage, inculding +Documentation of specific classes and function APIs and their usage, including their purpose, is embedded in the .h files defining that API. See [C++ style guide](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md) for pointers on how to write API documentatin in .h files. diff --git a/test/network/g3doc/g3doc.lua b/test/network/g3doc/g3doc.lua index af07b58b77..981393c826 100644 --- a/test/network/g3doc/g3doc.lua +++ b/test/network/g3doc/g3doc.lua @@ -1,4 +1,4 @@ -config = require('/g3doc/g3doc.lua') +config = super() config.freshness.owner = 'titovartem' diff --git a/test/pc/e2e/g3doc/g3doc.lua b/test/pc/e2e/g3doc/g3doc.lua index af07b58b77..981393c826 100644 --- a/test/pc/e2e/g3doc/g3doc.lua +++ b/test/pc/e2e/g3doc/g3doc.lua @@ -1,4 +1,4 @@ -config = require('/g3doc/g3doc.lua') +config = super() config.freshness.owner = 'titovartem'