Developer Quickstart#

In general, you should have vscode installed (which is fully supported by us).

We provide a dev container which might be a little more frictionless (because all dependencies are installed automatically in an isolated environment) or standard non container development.

What is better for you comes down to your personal preferences.

Developing in DevContainer#

Warning

if you’re on windows… You should be careful not to mount your windows filesystem into wsl2 / the devcontainer because this will be slow as hell regarding file io. This will be automatically the case if you clone your repo on a windows drive, open it in vscode and then open the devcontainer. Instead you can use one of the following approaches:

Open the repo in vscode devcontainer and follow the steps in the Usage section.

Developing natively (Windows or Linux)#

This is a little more work because you need to arrange prerequisites first.

Prerequisites#

In addition to the prequisites defined in the Getting Started Guide install the following tools if you haven’t them yet:

Usage#

  • open the devcontainer

    • if you installed the devcontainer cli just cd into the repo and type:

      devcontainer build  # for initially building or rebuilding the devcontainer
devcontainer open   # for opening the devcontainer directly in vscode

    • if not you can open vscode by typing:

      code

      When vscode opens you should see a notification asking you if you want to reload vscode in devcontainer - acknowledge it. (If that’s not working keep sure that you installed the remote container extension in vscode on your host).

  • Open the repo in vscode

  • On first start: install poetry packages and precommit hooks with vscode terminal (may take some time)

    poetry install
poetry run pre-commit install --install-hooks

  • in vscode select the python interpreter (Command Palette -> Python: Select Interpreter - if the poetry virtual env created before isn’t shown restart vscode and retry)

  • now you’re ready to develop

    • you can just hit F5 and should be able to debug into the code

    • you can also use the testrunner to run the unittests (or write some more for all the great features you’re implementing now 😉)

    • in vscode there are some tasks defined to manually run the precommit, lint etc. (usually you won’t need that if you installed precommit hooks)

  • For testing the doxysphinx cli you can also run it directly in the vscode terminal:

    poetry run doxysphinx <args...>

  • For just generating docs you can use the normal sphinx makefile mechanisms (A user would also do the same):

    make html # build complete documentation (doxygen, doxysphinx, sphinx)
make help # show commands
make clean # cleanup
make [doxygen|doxysphinx|sphinx] # run steps separately

    You can then see the generated documentation by opening .build/html/index.html.

Updating dependencies#

If you want to update the projects dependencies do the following:

  • checkin/stash all your local changes (so you could reverse easily and see the differences quite easy)

  • update your dependencies:

    poetry up --latest --without ci

  • review the updates e.g. in vscode with git diff

  • test everything 😄

Troubleshooting#

Module not found errors#

If you get module not found errors, e.g. when running doxysphinx or sphinx the problem might be the vscode terminal. Sometimes vscode isn’t activating the poetry virtualenv correctly in terminal (even if the rest of vscode is working). The solution is then to just restart the terminal (note that in the devcontainer you should use the zsh terminal).

screenshot on windows

Watch out for an venv activate script call or for the changed command prompt (the venv name should be at the beginning of the prompt).

Pycharm usage#

Hint

Should be the same for Intellij Idea.

While we recommend using vscode there are times when pycharm may be a better fit/ may be better suited for some dev tasks.

When opening the project in pycharm you may need to select the poetry executable. Under Windows this is installed in %USERPROFILE%\AppData\Roaming\Python\Scripts\poetry.exe (This path is as the time of this writing documented wrong in the poetry documentation so we mentioned that here).

Initialization will take some time in pycharm (especially when indexing the python sdk) so please be patient until everything is set up (watch the right side of the pycharm status bar).

Makefile targets under Windows#

We provide the makefile targets as run configurations. As Make is no standard tool under windows you would need to install it (e.g. via chocolatey “choco install make”), and afterwards configure it in Pycharm under File->Settings->Build, Execution, Deployment->Build Tools->Make->Path to Make executable.