Documentation Site

[s2t2]

Hi, I was getting back into this package and was interested in checking out some documentation.

So I created an auto-generated documentation site using Quarto and the quartodoc package.

It will automatically generate the documentation pages based on docstrings in the truthbrush package.

This PR is in draft status. I figured I would share, in case you would like to discuss, poke around, and further customize the documentation site (for example to use more of the README content).

Notes and Todos:

• I used a docs/requirements.txt file for specifying packages for the documentation site, but we would probably want to change that to use poetry (I wasn't entirely sure how)
• We can set up a GitHub Action to automatically publish the documentation site to GitHub pages. We would just need to update the "quarto-pages" workflow file to use poetry instead of installing from the requirements file.
• I chose "google" as the docstring type, because one of the functions uses that convention, but we can use "numpy" style instead, depending on your preference.

FYI I have published a copy of the documentation site with my fork, for reference:
https://s2t2.github.io/truthbrush/

---

---

[s2t2]

FYI regarding builds that are passing on my repo but failing on this upstream repo:

• the "python-application" build requires username and password to be set as repository secrets
• the "quarto-pages" build requires github pages to be set up

[s2t2]

I think this is ready for review, if we would like to implement the documentation site!

[milesmcc]

Hi! Thanks for putting this together. I'm a bit concerned about the maintenance burden -- is the value of the site really greater than the cost of maintaining it? I'm inclined to just keep the README high quality. I realize this is largely auto generated but it's another thing that we're going to have to think about.

[s2t2]

Hi @milesmcc thanks for your reply.

I would be happy to own / drive maintenance of the documentation site, if that is helpful.

Most of the effort has already been done in setting it up. Moving forward we would mainly need to focus on making sure functions have docstrings. The build process is automated through GitHub Actions so whenever we merge code into the main branch the docsite will update.

It has been helpful for me to look at my fork of the documentation site. I would love to be able to not have to maintain my own parallel fork separate from the main repo. But I understand if you ultimately would not like to implement the documentation site.

I'd be happy to discuss further, give a walkthrough of the main components, etc. Feel free to email me at prof.mj.rossetti@gmail.com if helpful.

[milesmcc]

Got it! Any chance you can move the test changes out of this PR? It'd be helpful to merge those even as we figure out how to best approach the documentation site (which I personally remain neutral about).

[s2t2]

Ok I will work on submitting a separate PR

…

On Wed, Sep 11, 2024, 1:18 AM R. Miles McCain ***@***.***> wrote: Got it! Any chance you can move the test changes out of this PR? It'd be helpful to merge those even as we figure out how to best approach the documentation site (which I personally remain neutral about). — Reply to this email directly, view it on GitHub <#38 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKENJ5QJRLZW2F4P7LFBTLZV7HD7AVCNFSM6AAAAABLBL6UYGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGNBSGY2DIOBSGI> . You are receiving this because you authored the thread.Message ID: ***@***.***>