#3333 assigned enhancement

Automate Conversion of Newlib Markup to Sphinx

Reported by: Joel Sherrill Owned by: Joel Sherrill
Priority: normal Milestone: Indefinite
Component: tool Version:
Severity: normal Keywords: SoC, ecosystem, Sphinx, docs, python
Cc: Blocked By:
Blocking:

Description

Incorporate Newlib Documentation into POSIX Users Guide

Contents

  1. Incorporate Newlib Documentation into POSIX Users Guide
    1. Mentors
    2. Status
  2. Introduction
  3. Project
    1. Goal
    2. Prerequisite
    3. Resources
  4. Tasks
    1. Regression Analysis
  5. Acknowledgements
  6. Miscellaneous Sections
  7. References

Mentors

Chris Johns
Joel Sherrill

Status

Looking for funding.

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

Change History (2)

comment:1 Changed on Mar 13, 2018 at 3:17:12 PM by Gedare

Keywords: ecosystem added

comment:2 Changed on Mar 13, 2018 at 3:17:57 PM by Gedare

Owner: set to Joel Sherrill
Status: newassigned
Note: See TracTickets for help on using tickets.