Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

131 add mkdocstrings to docu #134

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from

Conversation

JosePizarro3
Copy link
Collaborator

@JFRudzinski @Bernadette-Mohr or @EBB2675 @ndaelman-hu, would you mind taking a look?

You can locally launch the MKDocs page (check the README instructions), and see the new References section. Bear in mind we can change the style, but I do not want to spend to much time on this before deciding how the layout of the references should look like.

@JosePizarro3 JosePizarro3 linked an issue Sep 25, 2024 that may be closed by this pull request
@JosePizarro3 JosePizarro3 self-assigned this Sep 25, 2024
@JosePizarro3
Copy link
Collaborator Author

@JFRudzinski maybe you want to take a look on this and give improvement feedback.

I was also thinking that this docu generated shows that we need to describe better our objects.

@JFRudzinski
Copy link
Collaborator

just a note to the others: after I did

uv pip install -r requirements_docs.txt

I get ERROR - Config value 'plugins': The "mkdocstrings" plugin is not installed when I try to execute mkdocs. I just had to deactivate my env, and then reactivate and then it worked.

@JFRudzinski
Copy link
Collaborator

  • All of the http://purl.obolibrary.org/obo links are broken

@JFRudzinski
Copy link
Collaborator

JFRudzinski commented Oct 4, 2024

Screenshot from 2024-10-04 13-17-58

Is this the intended effect? Is it possible to change the format of the overview, e.g., display the overall type and then attributes in some sort of table or something. ATM it is easier to just read the source code.

Also, can we reduce the font size of the quantities? It is considerably larger than the normal font size throughout the docs

Sorry, I didn't see at first your comment about formatting.

I would suggest maybe something like:

name (Quantity(str)):
<description>

Not sure about for the ELN stuff

@JFRudzinski
Copy link
Collaborator

Screenshot from 2024-10-04 13-21-48

This is potentially very useful if we can leverage the admonisions in our descriptions. I wonder if we can also integrate some sort of equation display? That would be very nice

@JFRudzinski
Copy link
Collaborator

fixed a few things: #142

mostly I just added open is new browser tab for links to external sites

@JFRudzinski
Copy link
Collaborator

improvement feedback.

I was also thinking that this docu generated shows that we need to describe b

I definitely agree about improving the descriptions. I think for me it would be easiest to adjust the format first so that the description is easier to read, and then I could start going through and trying to make things more consistent/descriptive and tagging things that are unclear.

I could start this sooner, but then I would probably just go through the code and not use the docs. I think the former is better though cause then we can start utilizing the admonitions within the descriptions as mentioned above

What do you think?

@JosePizarro3
Copy link
Collaborator Author

improvement feedback.
I was also thinking that this docu generated shows that we need to describe b

I definitely agree about improving the descriptions. I think for me it would be easiest to adjust the format first so that the description is easier to read, and then I could start going through and trying to make things more consistent/descriptive and tagging things that are unclear.

I could start this sooner, but then I would probably just go through the code and not use the docs. I think the former is better though cause then we can start utilizing the admonitions within the descriptions as mentioned above

What do you think?

Yeah, agreed. I will take a look on formatting better this mkdocs page. And then we improve the descriptions in a subsequent pr so the docu will show nicely the results.

@coveralls
Copy link

Pull Request Test Coverage Report for Build 11180180474

Details

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage remained the same at 80.309%

Totals Coverage Status
Change from base Build 11027665277: 0.0%
Covered Lines: 2027
Relevant Lines: 2524

💛 - Coveralls

@JosePizarro3
Copy link
Collaborator Author

@JFRudzinski I was playing with MkDocs a bit more in another context, I think I can improve the documentation in this pr.

However, I wondered whether we are going to change the classes too much to make even sense. I guess we could discuss this next year in a meeting with the others like you suggested.

@JFRudzinski
Copy link
Collaborator

@JFRudzinski I was playing with MkDocs a bit more in another context, I think I can improve the documentation in this pr.

However, I wondered whether we are going to change the classes too much to make even sense. I guess we could discuss this next year in a meeting with the others like you suggested.

Oh ok, nice. I would very much like to learn about this (for other plugin docs as well). But yeah I agree we should wait till things are a bit more stable.

And yes, let's set a meeting starting next year, I will contact you.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add mkdocstrings to docu
3 participants