3. Drafting documents#

3.1. Enrich documentation#

  • Update the main branch and the intranet repository:

    « . /doc_build.sh sync

    If you’re working on a different branch, the script asks if you want switch to*hand*. If in doubt, answer*no* and switch manually later.

  • Create a branch:

    git checkout -b mc-demo

  • Edit documents…

3.2. Edit a document#

  • No dedicated application.

  • The documentation is modified like source code:

  • Location of documents:

    • source/manuals/man_r/r5/r5/r5.03.01/index.rst

    • source/manuals/man_r/r5/r5/r5.03.01/images/

    -… - source/intranet/man_u/u2/u2/u2.04.10/index.rst

3.3. Create a new document#

Before adding a new document, ask the maintainers the key for the new document (in the form x0.00.00).

We then do:

. /doc_build.sh created d8.99.99

IMPORTANT: For users with access to the intranet repository, the script asks if it is a document with restricted access.

+ document created: source/manuals/man_d/d8/d8.99.99

The main page of the document, index.rst, is created in the appropriate folder, as well as a page named page.rst (to be renamed according to use).

3.4. Submit changes#

The documentation is modified like source code in the Git repository.

  • Create a branch as indicated above:

    ``git checkout -b… ``

  • Check the status of the changes:

    git status

  • Save changes in a review

    ``git commit [-m « commit message »] ``

  • Push the branch:

    « . /doc_build.sh push``

  • Open a merge-request in the `gitlab-codeaster/doc/docaster`_ repository

    to incorporate branch changes.

Note

The same steps must be done in the intranet repository in case of changes

documents with restricted access.

In case of changes in both repositories, it is recommended to use the same branch name for the merge-request to build a coherent set.

3.5. Transition period#

  • The old application is stopped.

  • The v16 documentation is published in PDF.

  • The latest modified documents have been integrated in RST into the Git repository.

  • The impacts following developments in v17 must be written in

    the `gitlab-codeaster/doc/docaster`_ repository, submitted via a merge-request per form (+ intranet).

  • If a document already exists in ODT, it is possible from time to time to

    convert it to RST.

  • The documentation is available on the internet but

    only partially for now.

3.6. Ongoing improvements#

There are still a few generic fixes that can be scripted.

Errors should be corrected as changes are made.

Note

When you build a document, you have to correct all the mistakes

(messages ERROR or CRITICAL) and all warnings (messages WARNING). References to other documents may not be resolved during first construction. Relaunch once (or use the --twice option), there must be no more left.

For formatting errors, complete `issue < https://gitlab.pleiade.edf.fr/codeaster/doc/docaster/-/issues/2>#2`__ on GitLab.