-
Notifications
You must be signed in to change notification settings - Fork 142
API2Wiki
This page is about how to update wiki pages based on comments in the code.
Currently,automation tool for API comments to wiki pages is ready under ./openh264/docs/.
Configuration files for tool are under ./openh264/docs/doxygen/.
And API files used for tool is under ./openh264/codec/api/svc/.
- For tool requirement,please refer to section 5;
- For how to update the wiki pages step by step, please refer to section 2;
- For how to add Doxygen documentation format comments in the code,please refer to section 3.
- For how to change the wiki page layout,please refer to section 4.
-
In order to generate Doxygen style document for comments in code,you need to follow the Doxygen format.
-
For example:
/** * @brief initialize the encoder * @param pParam basic encoder parameter * @return CM_RETURN: 0 - success; otherwise - failed; */ virtual int EXTAPI Initialize (const SEncParamBase* pParam) = 0;
-
For more detail,please refer to section 3.
-
Run below command:
cd ./openh264/docs/doxygen doxygen
-
And Doxygen will generate xml files under ./openh264/docs/doxygen/_doxygen/xml.
-
All those xml files will be used in step 3 by python script.
-
Run below command:
cd ./openh264/docs python doxygen2rst.py
-
Wiki files will be generated under ./openh264/docs/wikipage.
-
Those files with suffix .rest will be push to wiki repository in step4 later.
-
For how to change the wiki page layout, please refer to section 4.
-
The wiki page is also a repository, which is independent of the source code.
-
Take openh264 for example:
https://github.com/cisco/openh264.wiki.git //repository for openh264 wiki page https://github.com/cisco/openh264.git //repository for openh264 source code
-
So you need to update the wiki repository with the latest wiki files under ./openh264/docs/wikipage.
git clone https://github.com/cisco/openh264.wiki.git YouFolderForWiki copy wiki files from ./openh264/docs/wikipage/ and replace the files under YouFolderForWiki/ git add -A git commit -m "you commit comment" git push origin master
-
And you can check and edit the wiki page if you want.
- ///< : for single line comment.
- /** my comments */ : for multi-line comments.
- @page: new page in html page. Currently, tool can add more than one pages under single wiki page.
- @brief: brief introduction for class,structure,function or pages etc.
- @param: function parameters description.
- @return: return value description.
- @code ... @endcode: example code.
-
For example:
/** * @page EncoderUsageExample1 * * @brief use basic parameter * * Step1:setup encoder * @code * int rv = WelsCreateSVCEncoder (&encoder_); * ASSERT_EQ (0, rv); * @endcode */
-
For more detail about Doxygen documentation format,please refer to: http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock
-
For Doxygen configuration,please refer to: http://www.stack.nl/~dimitri/doxygen/manual/config.html
-
Current API files setting in ./openh264/docs/doxygen/Doxyfile is:
INPUT = ../../codec/api/svc/codec_api.h ../../codec/api/svc/codec_app_def.h ../../codec/api/svc/codec_def.h
-
Configuration files are used to designed the wiki page layout.
-
Current configuration files for python script are listed as below:
Home.rest for wiki home page ISVEncoder.rest for class ISVCEncoder wiki page ISVDecoder.rest for class ISVCDecoder wiki page UsageExampleFoEnecoder.rest for encoder example usage wiki page UsageExampleForDecoder.rest for decoder example usage wiki page Note: each .rest configuration file maps to single wiki page.
-
You can add class, structure and page in any position of wiki pages.
-
For those pages with comment format "@page" in API files, you can add those pages in any position with below command in .rest configure files.
-
For example, add one page in home page, and add below info in configuration file Home.rest:
your description for this page <DoxyGen2RST page=PageName>
-
You can refer to file UsageExampleForEncode.rest as an example.
-
You can add any class in the API file if you want using below format in the .rest file.
your description for this class <DoxyGen2RST class=ClassName>
-
If you want to remove the class from the wiki page,just remove it from the .rest file.
-
You can refer to file ISVCEncoder.rest as an example.
-
You can add any class in the API file if you want using below format in the .rest file.
your description for this structure <DoxyGen2RST struct=StructureName>
-
If you want to remove the structure from the wiki page,just remove it from the .rest file.
-
It is the same with class.
-
As each .rest configuration file maps to a single wiki page, a new .rest file is needed if you want to add new wiki page.You can use one of the existing .rest file as template.
-
For how to place class,structure, page etc.,please refer to 4.1~4.3.
-
You need to add link in the home.rest for you new wiki page if you want by using below format in the home.rest:
`YourWikiPage <wiki/YourWikiPageName>`_
-
You can refer to home.rest as an example.
In order to transform API comments into wiki page,Doxygen and phython are needed.
- Doxygen is used to generate intermediate xml files which used in python script in next step.
- Please go to doxugen official website [Doxygen](http://www.stack.nl/~dimitri/Doxygen/) , and choose correct package based on your OS.
-
Python script is another tool used to transform the intermediate xml files into wiki format page.
-
Please go to python official website [Python](https://www.python.org/) and choose correct package bases on your OS.
-
The default version of this tools is python 2.7.
-
In addition, lxml library is needed in order to parse xml files.You can run below command to install lxml library.
For Mac OS or Windows: easy_install lxml
-
For more detail about the lxml installation, please refer to [lxml installation](http://lxml.de/installation.html)