[RTEMS Project] #3333: Automate Conversion of Newlib Markup to Sphinx
RTEMS trac
trac at rtems.org
Fri Feb 25 20:05:41 UTC 2022
#3333: Automate Conversion of Newlib Markup to Sphinx
-------------------------------------------------+-------------------------
Reporter: Joel Sherrill | Owner: Joel
| Sherrill
Type: enhancement | Status: assigned
Priority: normal | Milestone: Indefinite
Component: tool | Version:
Severity: normal | Resolution:
Keywords: SoC, ecosystem, Sphinx, python, | Blocked By:
large |
Blocking: |
-------------------------------------------------+-------------------------
Description changed by Joel Sherrill:
Old description:
> = Incorporate Newlib Documentation into POSIX Users Guide =
>
> [[PageOutline(1-5, Contents, inline)]]
>
> == Mentors ==
> Chris Johns
> Joel Sherrill
>
> == Status ==
>
> Thanks to a GSoC project, there is now a converter from the Newlib markup
> to Sphinx Rst. The next steps are:
>
> * incorporate generation into the rtems-docs build system
>
> * identifying an automated process to keep the RTEMS converted version in
> sync with Newlib. This could be maintainer mode only.
>
> * possibly reorganizing the POSIX Users Guide to reflect a per header
> file organization.
>
> = Introduction =
>
> RTEMS uses the Newlib C Library for a significant portion of its POSIX
> support. Newlib profiles most of the C99 Standard C Library including the
> math library (e.g. libc and libm). Currently, the RTEMS POSIX Users Guide
> will either not include documentation for these methods or provide
> documentation for a method not based on Newlib's.
>
> At this point, there is not a detailed design. This project is currently
> a desired capability.
>
> = Project =
>
> Newlib uses a project specific markup to include per method documentation
> embedded in the source code. There is a collection of programs (makedoc*)
> that read a source file, extract the embedded documentation, and output a
> specific markup format. Texinfo and Docbook are currently supported with
> host programs written in C or Python.
>
> This project involves writing a program or modifying an existing program
> to output Sphinx markup as is used by the RTEMS Documentation. Python is
> preferred for the source program. The Sphinx output will be one file per
> method and this output must be integrated into the RTEMS POSIX Users
> Guide.
>
> This integration is not a one-time activity. Periodically or at releases,
> the RTEMS Project will want to update those files. Thus integration
> requires defining a process and adding to support to the RTEMS
> Documentation build system and RTEMS Source Builder to enable updating
> the newlib content, building documentation with a specific version of
> newlib, etc. These would be in support of development and release
> activities.
>
> == Goal ==
>
> * Program to generate Sphinx from Newlib source markup.
> * Full integration with RTEMS Documentation Build.
> * Ability to update from a Newlib version.
> * Ability to include output from a specific Newlib version.
> * Proper support of RTEMS Release procedure.
>
> == Prerequisite ==
>
> * Knowledge of C programming language.
> * Knowledge of Python programming language.
> * Knowledge of Sphinx.
> * Requires Unix (Linux or FreeBSD) host.
>
> == Resources ==
>
> * Current RTEMS developers.
> * Newlib community.
>
> = Tasks =
>
> The following are the tasks:
>
> * TBD
>
> == Regression Analysis ==
>
> Automated testing of this capability is desired and must be identified.
>
> = Acknowledgements =
>
> None.
>
> = Miscellaneous Sections =
>
> As the project progresses, you will need to add to the procedural
> documentation of the RTEMS project including the release procedure
> and documentation generation prcedure.
>
> = References =
>
> * Sphinx - http://www.sphinx-doc.org/en/master/rest.html
> * Newlib - http://newlib.sourceware.org
> * Newlib documentation conversion tools -
> https://sourceware.org/git/gitweb.cgi?p=newlib-
> cygwin.git;a=tree;f=newlib/doc;h=603432d0756bb4470d6fac862c7edae22c7d6a9c;hb=HEAD
> * Newlib Python utility to produce Doxbook -
> https://sourceware.org/git/gitweb.cgi?p=newlib-
> cygwin.git;a=blob;f=newlib/doc/makedocbook.py;h=cf48c3402b5323d7e976aa6e37bdfcbd6ead6735;hb=HEAD
New description:
= Incorporate Newlib Documentation into POSIX Users Guide =
[[PageOutline(1-5, Contents, inline)]]
== Mentors ==
Chris Johns
Joel Sherrill
== Status ==
Thanks to a GSoC project, there is now a converter from the Newlib markup
to Sphinx Rst. The next steps are:
* incorporate generation into the rtems-docs build system
* identifying an automated process to keep the RTEMS converted version in
sync with Newlib. This could be maintainer mode only.
* possibly reorganizing the POSIX Users Guide to reflect a per header file
organization.
References to existing work:
* http://danxuehuang.blogspot.com/2018/
= Introduction =
RTEMS uses the Newlib C Library for a significant portion of its POSIX
support. Newlib profiles most of the C99 Standard C Library including the
math library (e.g. libc and libm). Currently, the RTEMS POSIX Users Guide
will either not include documentation for these methods or provide
documentation for a method not based on Newlib's.
At this point, there is not a detailed design. This project is currently a
desired capability.
= Project =
Newlib uses a project specific markup to include per method documentation
embedded in the source code. There is a collection of programs (makedoc*)
that read a source file, extract the embedded documentation, and output a
specific markup format. Texinfo and Docbook are currently supported with
host programs written in C or Python.
This project involves writing a program or modifying an existing program
to output Sphinx markup as is used by the RTEMS Documentation. Python is
preferred for the source program. The Sphinx output will be one file per
method and this output must be integrated into the RTEMS POSIX Users
Guide.
This integration is not a one-time activity. Periodically or at releases,
the RTEMS Project will want to update those files. Thus integration
requires defining a process and adding to support to the RTEMS
Documentation build system and RTEMS Source Builder to enable updating the
newlib content, building documentation with a specific version of newlib,
etc. These would be in support of development and release activities.
== Goal ==
* Program to generate Sphinx from Newlib source markup.
* Full integration with RTEMS Documentation Build.
* Ability to update from a Newlib version.
* Ability to include output from a specific Newlib version.
* Proper support of RTEMS Release procedure.
== Prerequisite ==
* Knowledge of C programming language.
* Knowledge of Python programming language.
* Knowledge of Sphinx.
* Requires Unix (Linux or FreeBSD) host.
== Resources ==
* Current RTEMS developers.
* Newlib community.
= Tasks =
The following are the tasks:
* TBD
== Regression Analysis ==
Automated testing of this capability is desired and must be identified.
= Acknowledgements =
None.
= Miscellaneous Sections =
As the project progresses, you will need to add to the procedural
documentation of the RTEMS project including the release procedure
and documentation generation prcedure.
= References =
* Sphinx - http://www.sphinx-doc.org/en/master/rest.html
* Newlib - http://newlib.sourceware.org
* Newlib documentation conversion tools -
https://sourceware.org/git/gitweb.cgi?p=newlib-
cygwin.git;a=tree;f=newlib/doc;h=603432d0756bb4470d6fac862c7edae22c7d6a9c;hb=HEAD
* Newlib Python utility to produce Doxbook -
https://sourceware.org/git/gitweb.cgi?p=newlib-
cygwin.git;a=blob;f=newlib/doc/makedocbook.py;h=cf48c3402b5323d7e976aa6e37bdfcbd6ead6735;hb=HEAD
--
--
Ticket URL: <http://devel.rtems.org/ticket/3333#comment:7>
RTEMS Project <http://www.rtems.org/>
RTEMS Project
More information about the bugs
mailing list