Hi All, I'm helping Adithi out with this project. If you are working on APIs and have any questions regarding how or where to document please let us know here or on Slack.
In general, API documentation should be in source files in doxygen format and module guides should be in their repos under the docs folder. e.g. mynewt-core/docs, mynewt-newt/docs. etc. Converting from mynewt-site/docs to mynewt-*/docs is a work in progress and quite manual but hopefully it will be complete prior to the next major release. Thanks, -Gavin On Tue, Oct 17, 2017 at 1:15 AM, aditi hilbert <[email protected]> wrote: > Hi all, > > With the Apache Mynewt codebase growing steadily, keeping up manually with > the API documentation is becoming untenable. So this is a heads-up about > moving to doxygen generated API documentation. I initiated the migration of > the technical documentation in PR #561 about a month back. An updated PR#619 > was merged today so everyone can start documenting the code and providing > feedback. > > To maintain consistency with the existing website and continue the > understandability of code with overviews/explanations/guidelines/tutorials, > the technical documentation structure and hierarchy will be preserved i.e. > relevant doxygen-generated API will be inserted into overview or explanation > document. One change required for this is to rewrite the markdown > overview/explanation documents to restructured txt. You can use the tool > “pandoc” to convert but the results are not always 100% accurate. > > So this is what’s on the table: > > 1) We insert a special comment block for Doxygen in the header files using > /** > * ... text ... > */ > > Note: We started off with the comment blocks in the .c files but most people > seem to prefer the header files. > > 2) We define a group using the \defgroup command in the special comment > block. Example: > https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_eventq.c > <https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_eventq.c> > > 3) You can define multiple groups in the same file. For example, the > following file has multiple groups: OSMqueue, OSMsys, OSMbuf > https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_mbuf.c > <https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_mbuf.c> > > The documentation files call the appropriate group(s) only. In this example, > https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mqueue/mqueue.rst > > <https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mqueue/mqueue.rst> > calls OSMqueue > https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/msys/msys.rst > > <https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/msys/msys.rst> > calls OSMsys > https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mbuf/mbuf.rst > > <https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mbuf/mbuf.rst> > calls OSMbuf > > 4) We could add a single link for several elements using overarching groups > defined using \addtogroup. For example, the entire API for the OS Kernel > could be generated using OSKernel. > > 5) You can build a local copy of the technical docs using the instructions at > https://github.com/apache/mynewt-core/tree/master/docs > <https://github.com/apache/mynewt-core/tree/master/docs> > You can then serve it up locally (e.g. “python -m SimpleHTTPServer 8080”) to > review it. > > One note: It’s better to get rid of the old build artifacts in _build > directory before doing another “make htmldocs”. > > thanks, > Aditi >
