Skip to content

[DOC] Inconsistent double tick quotes in docstrings #809

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

Closed
zy18811 opened this issue Oct 9, 2023 · 17 comments · May be fixed by #2627, #2695, #2709, #2718 or #2734
Closed

[DOC] Inconsistent double tick quotes in docstrings #809

zy18811 opened this issue Oct 9, 2023 · 17 comments · May be fixed by #2627, #2695, #2709, #2718 or #2734
Labels
documentation Improvements or additions to documentation good first issue Good for newcomers

Comments

@zy18811
Copy link
Contributor

zy18811 commented Oct 9, 2023

Describe the issue linked to the documentation

Single ticks render as italics while double ticks render as code in the api docs, e.g. int v.s. int. Various methods use this inconsistently, example from the HIVECOTE 2.0 docs below:

Docstring for random_state uses single ticks (italics) for all references to code, i.e. int, RandomState, and None.

image

Docstring for n_jobs uses double ticks for -1 to represent it referring to code.

image

Suggest a potential alternative/fix

Select preferred approach out of single and double ticks for referring to code in docstrings and apply consistently throughout aeon.

@zy18811 zy18811 added the documentation Improvements or additions to documentation label Oct 9, 2023
@TonyBagnall TonyBagnall added the good first issue Good for newcomers label Nov 24, 2023
@TonyBagnall
Copy link
Contributor

I think double ticks is preferable

@adityagh006
Copy link
Contributor

Hi @TonyBagnall, I'd like to work on this issue. Could you please assign it to me?

@MatthewMiddlehurst
Copy link
Member

Please read our contributor guide. It would be a bit much to do this for the whole package, why not select a module then post here that you will be working on it?

@Val-2608
Copy link
Contributor

Hi ,I'd like to work on resolving any inconsistencies in the documentation for the regression module.

@AnaghDeshpande
Copy link

Hi, @MatthewMiddlehurst i would like to work on anomaly_detection

@NasheetaFarzana
Copy link

Hello @MatthewMiddlehurst @TonyBagnall. I would like to work on this project. But as a beginner I need your guidance for how to start contributing ( mainly improving the documentation and docstrings ) in the code.

@MatthewMiddlehurst
Copy link
Member

Hi @NasheetaFarzana that depends on how experienced you are really. I would look at our contributing guide on the website. As i mentioned on Slack for stuff such as how to use Git, GitHub, or learning Python we are not the place unfortunetly.

@nMaax
Copy link

nMaax commented Mar 9, 2025

Hi @MatthewMiddlehurst , I noticed some inconsistencies in the segmentation module and would like to work on fixing them. It doesn't seem to me anyone else is working exactly on this module, just wanted to check if I can proceed.

Edit: Already forked and made commits on my fork's branch with all the updates, only thing to do now is the pull request

@nMaax
Copy link

nMaax commented Mar 10, 2025

Also, I was looking at PR #2574 and noticed that @MatthewMiddlehurst mentioned to do not insert double ticks in private docstrings (i.e. those related to modules not listed in __init__.py's __all__ variable) because they do not show on the webpage; although in PR #2546, if I'm not mistaken, changes of such kind were made. Should we then insert such double ticks also in the private docstrings for future PRs?

I decided to write this follow-up question here rather than in the Slack server so that also others can easily read about this detail when they first encounter this Issue, if this is not appropriate tell me and I will proceed to delete this comment and move it to Slack :)

@adityagh006
Copy link
Contributor

Hi @MatthewMiddlehurst, I'd like to work on resolving the double backtick inconsistencies in the similarity_search module.

@Ahmed-Zahran02
Copy link
Contributor

@aeon-actions-bot assign @MatthewMiddlehurst

@aeon-actions-bot aeon-actions-bot bot removed the good first issue Good for newcomers label Mar 15, 2025
@MatthewMiddlehurst MatthewMiddlehurst removed their assignment Mar 15, 2025
@MatthewMiddlehurst MatthewMiddlehurst added the good first issue Good for newcomers label Mar 15, 2025
@MatthewMiddlehurst
Copy link
Member

Undecided on whether we want it or not for private methods. Definitely want it for public ones.

@Ahmed-Zahran02
Copy link
Contributor

Hello @MatthewMiddlehurst ,
I would like to work on the backticks in "aeon/classification/distance_based".

@ISHOOO
Copy link

ISHOOO commented Mar 25, 2025

Hi @MatthewMiddlehurst , I'd like to work on the classification module. I will change all the single quotes (') to double backticks(``) in all the docstrings

@Tanish2503
Copy link

I noticed an inconsistency in how code elements are formatted in Aeon's docstrings—some references use single backticks (e.g., 'int', 'RandomState'), while others use double backticks (e.g., -1). This leads to inconsistent rendering in the API docs, where single backticks result in italics instead of proper code formatting.
To improve documentation clarity and maintain consistency, I propose updating all code references to double backticks (int, RandomState, None) across the project.
Would it be possible for me to get access or approval to proceed with this change? I can submit a PR with the necessary updates to ensure uniform formatting.

@Ahmed-Zahran02
Copy link
Contributor

Hello @MatthewMiddlehurst ,
I would like to work on the backticks in "base" module

@an04shu
Copy link

an04shu commented Mar 31, 2025

Hi, @MatthewMiddlehurst i would like to work on forecasting module

an04shu added a commit to an04shu/aeon_ that referenced this issue Apr 1, 2025
an04shu added a commit to an04shu/aeon_ that referenced this issue Apr 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment