search

acquire-project / acquire-docs

https://acquire-project.github.io/acquire-docs/
0 stars 3 forks source link

Autogenerate API documentation #80

Closed melissawm closed 3 months ago

melissawm commented 4 months ago

Depends on https://github.com/acquire-project/acquire-python/pull/198

This uses mkdocstrings to autogenerate API documentation for the entire Acquire module from the acquire.pyi file. I moved all of the existing docstring content to that file, so that PR needs to be merged first for this one to work.

I also need to figure out the build automation, which is why I am keeping this as a draft for now.

melissawm commented 4 months ago

Hello, folks! Here's an updated version of the docs, deployed: https://melissawm.github.io/acquire-docs/stable/api_reference/

I have followed the design suggestions, please let me know if this is reasonable. @dgmccart

melissawm commented 3 months ago

OOps! I just realized something went wrong with my deployment, will fix soon

EDIT: Fixed it. https://melissawm.github.io/acquire-docs/stable/api_reference/

melissawm commented 3 months ago

@dgmccart I have adjusted the font sizes for classes and methods to be 1.5rem and 1rem, respectively.

Here's how those looked before: Captura de imagem_20240729_150341

After the adjustment: Captura de imagem_20240729_150515

nclack commented 3 months ago

I'm so excited for this pr!

What's determining the labeling of methods as meth? Can that be changed? I'd prefer to spell it out as method or function.

melissawm commented 3 months ago

That is coming from mkdocstrings, but I am pretty sure we can change that. Would any of the other labels need to be changed as well?

dgmccart commented 3 months ago

Thank you Melissa! This looks great. I have just a few comments after reviewing the site with Janeece:

  1. Change the class color from blue to green
  2. Change the func color from purple to blue
  3. Change the tags to write out the whole word (e.g. meth --> method; func --> function)
  4. In the attributes table type column, use colors to indicate the different types. Since our class color will be green, we could use green for when the attribute's type is another class. Other types could have their own color as well. Is there a standard for code syntax highlighting we could use here?
melissawm commented 3 months ago

I don't think there is a standard, I'm not sure other themes use color coding for these properties. I'll try to stick with the same palette offered by material for mkdocs to make it consistent.

melissawm commented 3 months ago

A couple questions about item 4:

There are basically from what I can see two kinds of types for the attributes lists: types like int, float, str, list, dict and enum; and types that come from other classes in Acquire.

For the class-based types I can use the class color. What should I do for the others? As far as I can tell there is no standard for this so any guidance would be appreciated.

melissawm commented 3 months ago

Updated colors (items 1-3 of comment above) : https://melissawm.github.io/acquire-docs/dev/api_reference/

aliddell commented 3 months ago

@melissawm @dgmccart any objections if I merge now and remaining design work happens in a separate PR?

dgmccart commented 3 months ago

That sounds fine to me!

melissawm commented 3 months ago

Sounds good to me too! I'll be keeping an eye out for any trouble with the deployment step.

melissawm commented 3 months ago

Deployment is under /dev because I was expecting the version switcher to be deployed before this one, but it works 🎉

https://acquire-project.github.io/acquire-docs/dev/api_reference/