search

openzim / python-scraperlib

Collection of Python code to re-use across Python-based scrapers
GNU General Public License v3.0
18 stars 16 forks source link

Create/publish the user documentation #92

Open kelson42 opened 1 year ago

kelson42 commented 1 year ago

At this stage this seems necessary to publish a user documentation. Https://Readthedocs.com seems a good candidate.

kelson42 commented 1 year ago

Thanks to @benoit74 for reporting the problem

benoit74 commented 1 year ago

I'm not sure that we need to transform existing documentation. Adding a paragraph on all scrapers README with a link pointing to existing one would be sufficient from my PoV.

rgaudin commented 1 year ago

Probably a good first step

kelson42 commented 1 year ago

@benoit74 Your link is not the scraperlib documentation. Explaining the goals, the paradigm of the scraperlib and the dev facing API of the scraperlib is the puropose of this ticket.

rgaudin commented 1 year ago

I don't think this is the correct way to address what I believe the underlying issue is. What we need is a general Make/Contribute-to/ a Scraper documentation. This would fit with the other documents referenced above and would be actually useful while a standalone scraperlib doc won't be of much help to do so.

Sure we could gen the auto-doc off the source code but the value vs just browsing the code on Github would be minimal. Just afraid this would close this ticket without helping onboarding.

kelson42 commented 1 year ago

@rgaudin Not 100% sure I get you right. But I can only disagree with a comment which in a nutshell says "no need to document library API, devs who want to use it should read the code".

For the rest, general (cross repo) documentation can have a place in the "overview" repo. But, how to use the scraperlib does not match this definition IMO.

Lets discuss this in detail at the next meeting.

stale[bot] commented 1 year ago

This issue has been automatically marked as stale because it has not had recent activity. It will be now be reviewed manually. Thank you for your contributions.