Enriching the examples section on readthedocs

[jacadzaca]

The project can be improved with useful examples. The usage.rst file contains examples already. However, more examples will improve the clarity. Please use one of the issues mentioned below to extract an example and make a pull request.
Issues/tests that contain possible examples:

• converting icalendar into JSON -- a working example #85
• Converting events to Python dictionaries #210
• freebusy requests #267
• icalendar rrule only accept a dict, but dateutil.rrules are not dicts. #301
• how convert an ics to md, if (many) vevents don't have category #317
• how to automatically create event on google calendar #341
• How to modify a column of iCal in Python #342
• Problem with Event rrule format #421
• help getting values from ics file #425
• Add missing mandatory fields to user generated components #390 - generating RFC compliant TIMEZONE components
• Add example: invalid:nomail in ATTENDEE #130
• test_property_params and test_parse_and_access_property_params from test_property_params.py
• test_tools_UIDGenerator from test_unit_tools
• test_issue_116 from test_fixed_issues
• Show Yes No May be options in ICS file using Python #510

See Also

• This issues arises from refactor test_create_to_ical from test_encoding to test_examples.py #439.
• icalendar examples on readthedocs.
• When test .py and .rst files with doctest #445 is merged, the examples will be tested with doctest so we can make sure that they are actually working.

[niccokunzmann]

Comment removed because the issue is edited.

I think, adding the examples to a file for them or creating a file for them then allows running Python's doctest on them. So anyone who creates a pull request with an example of how to use icalendar will receive help so that the code is run by the test cases.

I do not have an overview over different kinds of examples that are already there. We do not want to duplicate code if not necessary and also make sure that the existing examples get tested and are where a beginner expects to see them.

I would like to see examples in the future also of how to read icalendar files and how to use the command line.

[abe-101]

Having used this library for a recent project of mine I feel the need for this initiative 😄
and I'm happy to help out

[abe-101]

Is there a specific strategy or structure we want with the examples in the docs?
Or do we want to add any useful (but random) example?

[jacadzaca]

Well, the way I'd go about this issue would be to create a separate Examples section on the website and start putting the examples listed here under different headings. I'd focus on the stuff like #267, #421 or #425 first, random but useful examples (like #85) would also be put up.