search

mxcube / mxcubecore

Backend used by MXCuBE
http://mxcube.github.io/mxcube/
GNU Lesser General Public License v3.0
11 stars 52 forks source link

Add doc generated from code and docstrings #806

Closed fabcor-maxiv closed 10 months ago

fabcor-maxiv commented 10 months ago

GitHub: fix https://github.com/mxcube/mxcubecore/issues/804

fabcor-maxiv commented 10 months ago

Preview: https://mxcubecore--806.org.readthedocs.build/en/806/dev/index.html

fabcor-maxiv commented 10 months ago

This is interesting example, it shows type hints, where types are links to another page of mxcubecore doc or to the Python doc: https://mxcubecore--806.org.readthedocs.build/en/806/dev/autosummary/mxcubecore.BaseHardwareObjects.html#mxcubecore.BaseHardwareObjects.HardwareObjectNode.get_objects

fabcor-maxiv commented 10 months ago

@rhfogh Is it what you had in mind? https://mxcubecore--806.org.readthedocs.build/en/806/dev/autosummary/mxcubecore.BaseHardwareObjects.html#mxcubecore.BaseHardwareObjects.HardwareObjectNode.get_objects

rhfogh commented 10 months ago

@fabcor-maxiv Not sure what you had in mind with your comment.

If you look at ConfiguredObject (the yml-configured superclass) there are basically two relevant functions: all_roles() which gives you a tuple of the roles of all contained objects and all_objects_by_role() which gives you an ordered dictionary of role:object. To get an object or a property by name, you simply do 'getattr(containerobj, name)' Note that all roles and property names are defined in the code and know in advance. And, NB, all roles and properties are specified in the class code. If you want properties whose name is not known at coding time, you can make (and code) a 'misc_properties' dictionary attribute, where you can put anything you want to stash.

HardwareObjectNode, by contrast has get_objects, has_object, get_object_by_role, objects_names, get_property, get_properties Note that the object name is NOT the same as the object role, but the (arbitrary) name of the xml configuration file that defines it. Note also that there is no way of knowing when you are coding which objects or properties are going to be defined, or how their name will be spelled.

fabcor-maxiv commented 10 months ago

@rhfogh I was only wondering if this kind of automatically generated documentation from the Python code and its docstrings is what you had in mind. I recall you asking for something like this during the code camp.

rhfogh commented 10 months ago

Ah! I really like this, it is great!

In general, what link should I follow to find the current generated documentation, once it is ready? https://mxcubecore--806.org.readthedocs.buildn looks kind of arbitrary

One thing that I feel is missing is showing the super- and subclasses, preferably with clickable links. It is hard to get anything out of e.g. HardwareObjectYaml if you cannot see how it fits in the inheritance hierarchy.

Also I think the Google style doc strings are not being used fully. See for instance the HardwareObjectNode.print_log function for an example.

But this a really good step forward, and I would not want to let my complaints overshadow that.

fabcor-maxiv commented 10 months ago

@rhfogh

The strange-looking URL is the URL for the preview of the pull request. The regular URL is https://mxcubecore.readthedocs.io/ and once things are merged I guess we will update the public links to this URL and probably make an announcement on the mailing list.

There are for sure improvements to be made, I agree, I am also somewhat disappointed by the results. It would be nice if you could open GitHub issue tickets with improvement suggestions and we can investigate them separately.

marcus-oscarsson commented 10 months ago

Thanks alot. Its nice with the automatically generated API documentation. It does seem partly quite outdated so we really need to make this common effort we have been speaking about to update it.

Whats really missing is something that ties everything together a broader architectural description with some nice examples. Ill try to help out with that, but I can't promise that it will be right away.

In general I also think that its nice if as much as possible can be derived from the code so that there is as little as possible to maintain in terms of documentation and less duplication between doc strings and "logic". That would probably also contribute to easier to understand code, as I think @axelboc was on to the other day.

As it is today the signatures in the documentation gets a bit cluttered with the doc string, like the example below.

image

It wold be interesting to see how far we get with just the type hinted signature, and if really really necessary some clarifications in the docstring. Its partly also a because the way is presented, sometimes the doc string can of course be very useful but then id prefer to expand it if needed somehow.

Otherwise, ascetically, it would be nice of the right hand menu would be larger so that it reads easier. There is maybe some other more palatable theme I find that this standard theme quickly becomes quite messy when one browses for some time, but thats maybe just me ?

Well just some thoughts :), its super nice to see this working !

marcus-oscarsson commented 10 months ago

I think we should start to look at when we could have the documentation code camp we spoke about :)

fabcor-maxiv commented 10 months ago

We should experiment with a different theme indeed. Maybe the Read the Docs theme or furo which has quite a lot of adoption lately.

fabcor-maxiv commented 10 months ago

@rhfogh

One thing that I feel is missing is showing the super- and subclasses, preferably with clickable links. It is hard to get anything out of e.g. HardwareObjectYaml if you cannot see how it fits in the inheritance hierarchy.

I have updated the config and it should now show the base classes, for example in the preview: https://mxcubecore--806.org.readthedocs.build/en/806/dev/autosummary/mxcubecore.BaseHardwareObjects.html#mxcubecore.BaseHardwareObjects.HardwareObjectYaml

fabcor-maxiv commented 10 months ago

@rhfogh

Also I think the Google style doc strings are not being used fully. See for instance the HardwareObjectNode.print_log function for an example.

I updated the config to take the Google style docstrings into account. See for example in this preview: https://mxcubecore--806.org.readthedocs.build/en/806/dev/autosummary/mxcubecore.BaseHardwareObjects.html#mxcubecore.BaseHardwareObjects.Equipment.print_log

marcus-oscarsson commented 10 months ago

Nice :), also cool with the themes :+1:

rhfogh commented 10 months ago

@fabcor-maxiv Excellent!

fabcor-maxiv commented 10 months ago

@marcus-oscarsson @rhfogh

If you are happy enough with this current state, let's merge it.

We can think of other improvements separately. I think tomorrow I will give other themes a try (in separate PR).

marcus-oscarsson commented 10 months ago

Awesome !

marcus-oscarsson commented 10 months ago

By the way the coverage report pipeline is killing me :)