Sphinx documentation

[wigging]

This adds Sphinx for generating documentation for the package. The Furo theme is also added for a more modern design and layout of the documentation pages. The associated dependencies are added to the optional docs group in the pyproject.toml file.

[wigging]

I will rebase this with the dev branch after the other pull request has been merged. The number commits for this pull request will be much lower after the rebase.

[wigging]

Since there are basically no docstrings in flowcept there isn't much documentation to generate. This will have to be improved with future pull requests. Read The Docs also needs to be setup so people can actually view the documentation but that can be done later too.

[renan-souza]

@wigging Is this PR ready to review?

Wrt adding docstrings to FlowCept, there is an open issue related to this: #50
We can benefit from a meeting to better explain how FlowCept is expected to be used and extended.

Perhaps we could work on it after we merge this PR.

[wigging]

Looks like I need to update the CONTRIBUTING.md with info on how to build the docs. I'll do that soon.

[wigging]

@renan-souza I added a few lines to the contributing document. I'll focus on resolving that issue in a separate pull request.

[renan-souza]

Looks like I need to update the CONTRIBUTING.md with info on how to build the docs. I'll do that soon.

Since you are changing it in this PR, do you mind adjusting the text that says we use black/flake for code formatting?

[wigging]

Black and Flake8 are not used in this project.

[renan-souza]

Black and Flake8 are not used in this project.

Exactly. But the CONTRIBUTING says they are. Since you are updating the CONTRIBUTING, can you please update the text in it where it mentions those and update with what we are currently using for code formating?

[wigging]

Cleaned up the contributing guidelines and added more info about code linting and formatting.

[wigging]

I added a Makefile in the root directory of the project to help with various commands such as running checks, running tests, starting containers, etc. This is especially helpful for Docker commands which I can never remember.

[wigging]

@renan-souza I don't have anything else to add to this pull request.

[renan-souza]

@renan-souza I don't have anything else to add to this pull request.

Sounds good. I will start reviewing it and add new commits if needed.

[renan-souza]

@wigging Before we merge this PR, I would feel more comfortable if we tested the sphinx docs procedure.

Do you mind adding a new CI workflow based on https://github.com/ORNL/flowcept/blob/sphinx-docs/.github/workflows/run-checks.yml to test if the documents are being generated correctly?

This workflow can run only on PRs, just like the run-checks.yml.

Also, you could create a new command in Flowcept's Makefile to generate the documents.

Once we put sphinx as part of the CI process and it passes the test, I'll merge & close this PR.

[wigging]

It builds fine on my local computer but I'll add something to the GitHub Actions to check the build too. And Sphinx already provides a Makefile (see docs/Makefile) for building the documentation and doing other things.

[renan-souza]

It builds fine on my local computer but I'll add something to the GitHub Actions to check the build too.

Thanks. The goal is to increase the test coverage of all these features we add into the project.

And Sphinx already provides a Makefile (see docs/Makefile) for building the documentation and doing other things.

Yea, I saw that, that's fine, but since we now have our own Makefile, it's more convenient to use that same Makefile for everything rather having multiple Makefiles and cd into a directory to run it.

[wigging]

Yea, I saw that, that's fine, but since we now have our own Makefile, it's more convenient to use that same Makefile for everything rather having multiple Makefiles and cd into a directory to run it.

You can pursue this in a separate pull request. This pull request is about setting up Sphinx, not fiddling around with Makefiles. The Makefile in the docs directory is generated by Sphinx and it uses the underlying sphinx CLI commands. Those commands expect to be run from the root level of the docs directory. I don't know what all these commands are but you will have to avoid naming conflicts if you do a recursive Makefile. You also would need to properly handle the path to the sphinx config file and other files if you try to use a top-level Makefile. Just cd into the docs directory and use the Sphinx Makefile as intended.

[wigging]

@renan-souza Did something change on the dev branch to cause the tests to fail? None of the changes in this pull request should affect the tests.

[renan-souza]

@renan-souza Did something change on the dev branch to cause the tests to fail? None of the changes in this pull request should affect the tests.

Nothing has changed that could cause that error. Not sure what happened. I'll need to debug.

[wigging]

All of the errors and test failures seem to be caused by code that uses Dask.

[renan-souza]

All of the errors and test failures seem to be caused by code that uses Dask.

Yes and nothing about Dask has changed on our side.
Since the CI always installs the newest version of these dependencies, I suspect that something changed in the newest version of Dask that caused this error.

Please ignore these Dask errors as they have nothing to do with your chages.

I'll need to dig into this later.

[wigging]

I went ahead and added the Makefile commands to build/clean the Sphinx docs from the top-level of the project. I removed the Makefile in the docs directory. I also added the Makefile commands in the run-checks workflow.

[wigging]

@renan-souza Anything else needed here?