gazebosim / gazebosim/docs

Add a tutorial explaining how to contribute documentation

Open
#148 2 comments 0 reactions 0 assignees View on GitHub
documentation enhancement help wanted
Dominant language
Python
Stars
88
Forks
319
Avg merge
2h 2m
Merged PRs (30d)
1

Description

## Desired behavior

We want users to contribute documentation, but it's not always straightforward how to do it. We have some tips on generating API docs in the [code contributing guide](https://ignitionrobotics.org/docs/all/contributing), but I think there's enough to explain about documentation to prompt its own tutorial.

## Alternatives considered

We can also keep this documentation together with the code contribution docs, but I think we could at least give it more context and make it easier to find.

## Implementation suggestion

Things to document:

* How the API docs and per-library tutorials are generated using doxygen and can be tested locally (some explanation already in each install tutorial, i.e. [here](https://ignitionrobotics.org/api/common/3.10/install.html))
* The fact that the API docs are [deployed nightly](https://github.com/ignitionrobotics/docs/blob/master/.github/workflows/nightly-upload.yml)
* How the docs on this site are using custom code on a private repository to be generated, are deployed on demand, and can't be tested locally yet (#85)

## Additional context

This came up in https://github.com/ignitionrobotics/docs/issues/145#issuecomment-780026297 and https://github.com/ignitionrobotics/docs/pull/147

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the code contributing guide and the linked install tutorial, then inspect .github/workflows/nightly-upload.yml and issue #85 for the existing generation and deployment details. Document how API and per-library tutorials are generated and tested, how API docs are deployed nightly, and how site docs are generated and deployed on demand; note the current lack of local testing for the private tooling.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions
Domain
ci-cd, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.