Contributing

The Apache NuttX Companion is made using the Sphinx documentation system. Sphinx documentation is written in ReStructured Text (RST). RST is the format used for Python documentation and is also used in many other projects.

Contributions and fixes to the Apache NuttX Companion are encouraged and welcome. Here’s how to do it.

  1. Fork the Apache NuttX Companion Repository

    Visit this link and hit the Fork button in the upper right of the page:


  2. Clone the Forked Repository

    Click the “Clone or Download” button and copy the clone URL. Then do this:

    $ git clone <CLONE-URL-THAT-YOU-COPIED>

  3. Install Sphinx

    On the command line, change directories to the newly-downloaded repository directory:

    $ cd nuttx-companion
$ # install pyenv
$ curl -L https://github.com/pyenv/pyenv-installer/raw/master/bin/pyenv-installer | bash
$ # install python
$ pyenv install 3.6.9
$ # install pipenv
$ pip install pipenv
$ # install sphinx
$ pipenv install
$ # activate the virtual environent
$ pipenv shell

  4. Build the HTML Documentation Locally

    $ cd docs
$ make html
Running Sphinx v2.4.1
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 12 source files that are out of date
updating environment: [new config] 12 added, 0 changed, 0 removed
reading sources... [100%] user/simulator
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] user/simulator
generating indices...  genindexdone
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in ``_build/html``.

  5. Check Out a New Branch

    $ git checkout -b feature/my-branch

  6. Make Your Changes

    $ vim user/quickstart.rst  # or use the editor of your choice
                           # on whatever file you want to change

  7. Rebuild the HTML Documentation

    $ make html

  8. View the Documentation in a Web Browser

    You can open the file docs/_build/html/index.html.

  9. Iterate

    Repeat Steps 6, 7, and 8 until you’re happy with the result.

  10. Commit the Changes

    $ git add user/quickstart.rst  # or whatever files you changed
$ git commit

  11. Push to Your Branch

    $ git push

  12. Submit Your Pull Request

    Go to the Apache NuttX Companion page on Github and click the “Pull Request” button. See Github’s Creating a Pull Request page for more info.

    Use this template for the Pull Request description text:

    ### Summary
### Impact
### Limitations / TODO
### Detail
### Testing
### How To Verify

    Fill out the sections describing your changes. The summary should be a concise bulleted list.

    The How To Verify section is only needed if you change how the project is built or add some other programs or scripts.

  13. Make Changes If Requested

    When you submit your Pull Request, the Apache NuttX Companion team will review the changes, and may request that you modify your submission. Please work with them to get your changes accepted.

  14. You’re Done!

    Feel good that you’ve made Apache NuttX documentation better for yourself and others. You’ve just made the world a better place!