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 | 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!