Page MenuHomePhabricator

[clonable] Improve docstrings to the Pywikibot library
Open, MediumPublic

Description

Documentation is automatically extracted from the docstrings in the Pywikibot library, and converted into html using Sphinx to create
https://doc.wikimedia.org/pywikibot/api_ref/index.html

Many methods in the library do not have adequate docstrings that describe the parameters, return type and exceptions that may occur.

These should be added to docstrings using epytext fields.

When you amend a docstring and submit it to Gerrit, a Jenkins job will automatically validate the docstring, and -1 the changeset if it includes syntax errors.

Easy GCI task: amend one docstring to completely and accurately summarise its behaviour, documentings its inputs and outputs.

Mentor: @jayvdb

Event Timeline

jayvdb created this task.Nov 11 2015, 9:38 PM
jayvdb raised the priority of this task from to Medium.
jayvdb updated the task description. (Show Details)
jayvdb added a subscriber: jayvdb.
Restricted Application added a project: Documentation. · View Herald TranscriptNov 11 2015, 9:38 PM
Restricted Application added subscribers: pywikibot-bugs-list, Aklapper. · View Herald Transcript

I will be a mentor for this task.

jayvdb renamed this task from Improve docstrings to the Pywikibot library to [clonable] Improve docstrings to the Pywikibot library.Nov 11 2015, 9:51 PM
jayvdb set Security to None.
jayvdb updated the task description. (Show Details)Dec 1 2015, 8:58 PM

Change 262420 had a related patch set uploaded (by Sn1per):
Add/improve docstrings for miscellaneous functions

https://gerrit.wikimedia.org/r/262420

Change 262667 had a related patch set uploaded (by Sn1per):
Expand docstring for pagegenerators.LinkedPageGenerator

https://gerrit.wikimedia.org/r/262667

Change 262668 had a related patch set uploaded (by Sn1per):
Add docstring for cosmetic_changes.CosmeticChangesToolkit.cleanUpLinks

https://gerrit.wikimedia.org/r/262668

Change 262420 abandoned by Sn1per:
Add/improve docstrings for miscellaneous functions

Reason:
Split into:

  • If575c131b44cb42c7d6d392b55ba35c3cc1398a3 (pagegenerators.LinkedPageGenerator)
  • 1b655412a4dfaf4c287658d5a012d3bbb46de7e7 (cosmetic_changes.CosmeticChangesToolkit.cleanUpLinks)

https://gerrit.wikimedia.org/r/262420

Change 262667 merged by jenkins-bot:
Expand docstring for pagegenerators.LinkedPageGenerator

https://gerrit.wikimedia.org/r/262667

Change 262668 merged by jenkins-bot:
Add docstring for cosmetic_changes.CosmeticChangesToolkit.cleanUpLinks

https://gerrit.wikimedia.org/r/262668

This comment was removed by Dvorapa.

@Dvorapa: Do you plan to mentor this task? If so feel free to create it on the GCI site. :)

Yes, I'll find some spare time and make GCI tasks for this

@Dvorapa: You have two more weeks for Google-Code-in-2018, if you still plan to. :)

Hello @Dvorapa
Is this task still open? Can I work on it?

Dvorapa added a comment.EditedMar 17 2019, 3:24 PM

Hello @Didicodes, yes, it was still not marked as resolved as there are still many methods, that need proper docs. Choose some and try to improve them. Common errors are missing params and return value descriptions, missing links to API or to related methods, missing code samples and ilustrative demonstrations.

Didicodes added a comment.EditedMar 17 2019, 3:42 PM

Great @Dvorapa. To do this, I need to clone the pywikibot repository here right? Then improve the documentation of some methods. Kindly tell me the steps to follow. I am a new contributor! Thank you.

Not really, see https://www.mediawiki.org/wiki/Manual:Pywikibot/Development for the basics of how to contribute to Pywikibot. GitHub is just a mirror of our code review system on Gerrit. There is a nice manual in https://www.mediawiki.org/wiki/Manual:Pywikibot/Gerrit and also you can see much detailed steps in https://www.mediawiki.org/wiki/Gerrit/Tutorial.

Change 497205 had a related patch set uploaded (by Didicodes; owner: Didicodes):
[pywikibot/core@master] Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497205

Change 497205 merged by jenkins-bot:
[pywikibot/core@master] Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497205

Change 497580 had a related patch set uploaded (by Nikitrain; owner: Nikitrain):
[pywikibot/core@master] Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497580

Change 497580 abandoned by Nikitrain:
Improve docstrings to the Pywikibot library

Reason:
I'm going to send another patch with the same changes.

https://gerrit.wikimedia.org/r/497580

Change 497786 had a related patch set uploaded (by Nikitrain; owner: Nikitrain):
[pywikibot/core@master] Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497786

Change 497786 abandoned by Nikitrain:
Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497786

Change 497804 had a related patch set uploaded (by Nikitrain; owner: Nikitrain):
[pywikibot/core@master] Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497804

Change 497804 merged by jenkins-bot:
[pywikibot/core@master] Improve docstrings to the Pywikibot library

https://gerrit.wikimedia.org/r/497804