search

qutip / qutip-tensorflow

TensorFlow linear-algebra backend for QuTiP
BSD 3-Clause "New" or "Revised" License
15 stars 9 forks source link

Create initial Sphinx documentation skeleton #3

Closed jakelishman closed 3 years ago

jakelishman commented 3 years ago

This is close to the base sphinx-quickstart setup, except the conf.py file is tidied up with automatic versioning and a base set of extensions for parsing docstrings and readthedocs formatting.

There is also a GitHub Action to ensure that the documentation is tested on each pull request, so that improperly formatted dosctrings can't sneak through.

coveralls commented 3 years ago

Pull Request Test Coverage Report for Build 915588058

Totals Coverage Status
Change from base Build 914138743: 0.0%
Covered Lines: 4
Relevant Lines: 4
💛 - Coveralls
jakelishman commented 3 years ago

Also, to answer the main question in your review: for the most part, yes, but it's not infallible. The Sphinx build is set up so that it treats warnings as errors, and reporting an error causes it to fail the CI action. However, this isn't entirely bullet-proof; there are lots of ways you can totally mess up rst formatting without technically emitting a warning. The general idea is to catch us from accidentally putting in incorrect section names, or putting in crossreferences which don't actually link to anything. There's no automated tool in the world that can distinguish "what you meant" from "what you wrote", though.

AGaliciaMartinez commented 3 years ago

Ok, got it! I will now merge this pull request.

jakelishman commented 3 years ago

That's it for my PRs for now. You've got a complete skeleton for a Python package with tests, documentation and CI actions, so now it's up to you to populate it! Hopefully you understand how everything works, and why it's written the way it is. You'll likely add to everything here, so feel free to ask more if you have further questions later.