search

musicfox / pycmc

A Python interface for the chartmetric.com API
MIT License
21 stars 2 forks source link

Migrate docstrings to Markdown format #11

Closed thinkjrs closed 4 years ago

thinkjrs commented 4 years ago

Our docstrings get an upgrade

What's a docstring you say?

"""
I am a docstring.
"""
"""
# I am
## therefore 
### a markdown
`docstring`
"""

The docstring is just the portion between three quotation marks """. They're used to generate documentation and for inline help in IDEs and other things.

For example...

Here's a nice markdown docstring rendering of the docstring in pycm/utilities for the function strDateToday.

image

Files that need looking at

Ignore the other items but here's the list: Filename Hit Miss Excluded %
pycm/init.py 13 0 0 100%
pycm/album.py 35 25 0 29%
pycm/artist.py 70 55 0 21%
pycm/background.py 26 5 0 81%
pycm/chart_cleaners.py 212 202 0 5%
pycm/charts/init.py 0 0 0 100%
pycm/charts/amazon.py 12 8 0 33%
pycm/charts/applemusic.py 17 12 0 29%
pycm/charts/beatport.py 7 4 0 43%
pycm/charts/cm_score.py 16 12 0 25%
pycm/charts/deezer.py 7 4 0 43%
pycm/charts/itunes.py 17 12 0 29%
pycm/charts/qq.py 7 4 0 43%
pycm/charts/shazam.py 13 9 0 31%
pycm/charts/soundcloud.py 7 4 0 43%
pycm/charts/spotify.py 14 8 0 43%
pycm/charts/youtube.py 24 16 0 33%
pycm/credentials.py 66 23 0 65%
pycm/credentials_manager.py 30 11 0 63%
pycm/curator.py 23 17 0 26%
pycm/playlist.py 27 21 0 22%
pycm/recommendation.py 12 10 0 17%
pycm/search_engine.py 10 8 0 20%
pycm/track.py 39 31 0 21%
pycm/utilities.py 36 13 0 64%

Doing one together

  1. Clone the repo: git clone git@github.com:musicfox/pycm.
  2. Update your repo and start a new branch (from inside the pycm repo project directory): git pull origin develop && git flow feature start markdown-docstrings.
  3. Open up album.py under the pycm source directory (pycm/pycm).

  4. Let's fix the docstring in the first charts function, which looks like:

    def charts(stype, cmid, start_date, end_date=None):
"""
Query the charts for the given album of a selected streamer type. 

https://api.chartmetric.com/api/album/:id/:type/charts

:param stype:           string streaming platform, choose from
                        'applemusic', 'itunes' or 'amazon'
:param cmid:            string or int chartmetric album ID
:param start_date:      string start data in ISO format
:param end_date:        string end date in ISO format

:return:                list of dictionaries of the chart for
                        the given album
"""
logging.info(
    f"This is known to have authentication issues when "
...

  5. Now alter the doctring to look like:

    """
# `charts`
Query the charts for the given album of a selected streamer type. 

https://api.chartmetric.com/api/album/:id/:type/charts

## Parameters
- `stype`: string streaming platform, choose from
               'applemusic', 'itunes' or 'amazon'
- `cmid`: string or int chartmetric album ID
- `start_date`: string start data in ISO format
- `end_date`: string end date in ISO format

## Returns
A list of dictionaries of the chart for the given album.
"""
  6. Save your work and move to the next function. Repeat. Loop. Almost.Forever. Until you're done with one file.
  7. Stage + commit the result: git add path/to/my.file && git commit -m ":pencil: update docstrings #11"
  8. Open up a new file and repeat the entire process until finished.
  9. After your last one, commit + push: git push origin feature/markdown-docstrings
thinkjrs commented 4 years ago

@philipmuh Now that I think of it, go ahead and push commits as you go. I'll open up a PR so they all track together.