Add rfc documentation #730

Firdous2307 · 2024-10-13T21:14:16Z

RFC 5545 Documentation Addition

This merge request adds motivational text from RFC 5545 to the following calendar components:

Alarm
Event
Todo
FreeBusy
Timezone (including subclasses TimezoneStandard and TimezoneDaylight)
Calendar

Changes

The added documentation provides a brief description of each component's purpose and functionality, as defined in the RFC. This change:

Improves the overall documentation of the library
Helps developers better understand the purpose of each component

Timezone Component

Special attention was given to the Timezone component and its subclasses (TimezoneStandard and TimezoneDaylight) to accurately represent their roles in defining time zone information.

Note

The Journal component was already documented and served as an example for the other components.

These changes address issue #726 and enhance the codebase's alignment with the RFC specifications.

# Example of added documentation
class Event(Component):
    """
    An "VEVENT" calendar component is a grouping of component
    properties that represents a scheduled amount of time on a
    calendar. For example, it can be an activity; such as a one-hour
    long, department meeting from 8:00 AM to 9:00 AM, tomorrow.
    """
    # ... existing code ...

📚 Documentation preview 📚: https://icalendar--730.org.readthedocs.build/

…r into support-python-3.13

…subclasses

Firdous2307 · 2024-10-13T21:14:42Z

@niccokunzmann Kindly check my PR

coveralls · 2024-10-13T21:20:38Z

Pull Request Test Coverage Report for Build 11317751379

Details

1 of 1 (100.0%) changed or added relevant line in 1 file are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.001%) to 97.337%

Totals
Change from base Build 11317448813:	0.001%
Covered Lines:	3501
Relevant Lines:	3593

💛 - Coveralls

niccokunzmann · 2024-10-13T21:23:25Z

docs/maintenance.rst

@@ -148,3 +148,16 @@ This section contains useful links for maintainers and collaborators:

 - `Future of icalendar, looking for maintainer #360 <https://github.com/collective/icalendar/discussions/360>`__
 - `Comment on the Plone tests running with icalendar <https://github.com/collective/icalendar/pull/447#issuecomment-1277643634>`__
+


Could you create a new PR without the old code?

You can look up how to

create a new branch

use git cherry-pick to move the commits over.

I am confused, can you explain better?

Sure! When I look at the commits here:

https://github.com/collective/icalendar/pull/730/commits

It seems that you added the commits of the other PR into this PR.
That is not what is usually done on GitHub: Each PR should be able to stand alone, be merged and reviewed alone.

There is this one commit here:

That is the only one that should go into this PR. Basically this PR should be based on the main branch of collective/icalendar and go to the main branch of collective/icalendar with one additional commit, nothing else.

This way, we do not get confused and re changes only show up in one PR and do not need addressing in different placed. This is also an old library, so it is good to keep a bit of discipline because we might need to know why changes happened 10 years later.

You should be able to do this:

git checkout a27b146f50c1ddd83117302372d0704ce8ff0853 # the commit git checkout -b new-branch-for-PR git push -u origin new-branch-for-PR

And create a new PR without the other things.

Okay @niccokunzmann I understand now, I'll work on that.

stevepiercy

Minor English grammar fixes, and remarks on change log.

stevepiercy · 2024-10-13T21:52:32Z

CHANGES.rst

You need to merge main into your branch to update this file. 6.0.1 was released 5 hours ago.

Then add your changes that this PR makes to this file under the correct version heading and topic subheading.

stevepiercy · 2024-10-13T21:56:28Z

docs/maintenance.rst

+2. `tox.ini`: Update the `envlist` to include or remove the Python version.
+3. `pyproject.toml`: Update the `requires-python` line and the `classifiers` list.
+4. `README.rst`: Update the compatibility information.
+5. `docs/maintenance.rst`: Update this list if any new files need to be modified.


For readability, I would convert this enumerated list to a definition list, and remove : after each term. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks

Also inline literals in reStructuredText should use double backticks, not single as in Markdown.

stevepiercy · 2024-10-13T21:56:52Z

src/icalendar/cal.py

@@ -549,6 +549,12 @@ def is_datetime(dt: date) -> bool:
    return isinstance(dt, datetime)

 class Event(Component):
+    """
+    An "VEVENT" calendar component is a grouping of component


Suggested change

An "VEVENT" calendar component is a grouping of component

A "VEVENT" calendar component is a grouping of component

stevepiercy · 2024-10-13T21:57:41Z

src/icalendar/cal.py

+    """
+    An "VEVENT" calendar component is a grouping of component
+    properties that represents a scheduled amount of time on a
+    calendar. For example, it can be an activity; such as a one-hour


Suggested change

calendar. For example, it can be an activity; such as a one-hour

calendar. For example, it can be an activity, such as a one-hour

stevepiercy · 2024-10-13T21:57:54Z

src/icalendar/cal.py

+    An "VEVENT" calendar component is a grouping of component
+    properties that represents a scheduled amount of time on a
+    calendar. For example, it can be an activity; such as a one-hour
+    long, department meeting from 8:00 AM to 9:00 AM, tomorrow.


Suggested change

long, department meeting from 8:00 AM to 9:00 AM, tomorrow.

long department meeting from 8:00 AM to 9:00 AM tomorrow.

stevepiercy · 2024-10-13T21:58:09Z

src/icalendar/cal.py

@@ -693,6 +699,13 @@ def end(self, end: date | datetime | None):


 class Todo(Component):
+    """
+    A "VTODO" calendar component is a grouping of component
+    properties that represents an action-item or assignment. For


Suggested change

properties that represents an action-item or assignment. For

properties that represents an action item or assignment. For

stevepiercy · 2024-10-13T21:58:21Z

src/icalendar/cal.py

+    A "VTODO" calendar component is a grouping of component
+    properties that represents an action-item or assignment. For
+    example, it can be used to represent an item of work assigned to
+    an individual; such as "Prepare for the upcoming conference


Suggested change

an individual; such as "Prepare for the upcoming conference

an individual, such as "Prepare for the upcoming conference

niccokunzmann · 2024-10-14T14:06:44Z

@Firdous2307 How is it going, how are you? Let me know if you need anything or have questions how to go on. GitHub is not always easy.

Firdous2307 · 2024-10-15T22:08:34Z

@Firdous2307 How is it going, how are you? Let me know if you need anything or have questions how to go on. GitHub is not always easy.

@niccokunzmann Thanks for the help, I have created a new branch and cherry picked the specific commit. I want to push a new commit to that new branch and fix the mistake english spellings

Firdous2307 · 2024-10-15T22:14:08Z

@niccokunzmann Should I just fix the Mistake spellings and the suggestion @stevepiercy made on the docs/maintenanc.rst on this branch. Then the new branch will be only for that specific commit as stated earlier.

I think that will help me reduce work instead of merging this branch with the new one, let me know wht you think

niccokunzmann · 2024-10-16T11:08:27Z

@Firdous2307, I think that you could close the PR and create a new one. The grammar fixes pointed out can be applied to the files in the new PR manually on your computer. Is that good for you?

Firdous2307 · 2024-10-16T11:20:07Z

@Firdous2307, I think that you could close the PR and create a new one. The grammar fixes pointed out can be applied to the files in the new PR manually on your computer. Is that good for you?

@niccokunzmann Yeah sure no problem.

niccokunzmann · 2024-10-22T10:04:21Z

@Firdous2307 Thanks, I will close this now and if you do not mind, you can create a new one. If you find that too much work, I can also create one and git cherry-pick the commit that is useful.

Follow up #730 - rfc 5545 docs on components

Firdous2307 and others added 6 commits October 13, 2024 21:10

feat: Add support for Python 3.13

f340491

docs: Document process for updating Python versions

d81ca62

Merge branch 'main' into support-python-3.13

79624c7

docs: Update CHANGES.rst for Python 3.13 compatibility

49c11aa

Merge branch 'support-python-3.13' of github.com:Firdous2307/icalenda…

e9d0e1a

…r into support-python-3.13

feat: Add RFC 5545 documentation to calendar components and timezone …

a27b146

…subclasses

niccokunzmann reviewed Oct 13, 2024

View reviewed changes

stevepiercy requested changes Oct 13, 2024

View reviewed changes

niccokunzmann mentioned this pull request Oct 13, 2024

Support python 3.13 #729

Merged

2 tasks

niccokunzmann closed this Oct 22, 2024

niccokunzmann reopened this Oct 26, 2024

niccokunzmann closed this Oct 26, 2024

niccokunzmann added a commit that referenced this pull request Oct 26, 2024

Merge pull request #738 from niccokunzmann/rfc-docs

569c40b

Follow up #730 - rfc 5545 docs on components

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add rfc documentation #730

Add rfc documentation #730

Firdous2307 commented Oct 13, 2024 •

edited by github-actions bot

Loading

Firdous2307 commented Oct 13, 2024

coveralls commented Oct 13, 2024

niccokunzmann Oct 13, 2024

Firdous2307 Oct 13, 2024

niccokunzmann Oct 14, 2024

niccokunzmann Oct 14, 2024

Firdous2307 Oct 14, 2024

stevepiercy left a comment

stevepiercy Oct 13, 2024

stevepiercy Oct 13, 2024

stevepiercy Oct 13, 2024

stevepiercy Oct 13, 2024

stevepiercy Oct 13, 2024

stevepiercy Oct 13, 2024

stevepiercy Oct 13, 2024

niccokunzmann commented Oct 14, 2024

Firdous2307 commented Oct 15, 2024 •

edited

Loading

Firdous2307 commented Oct 15, 2024

niccokunzmann commented Oct 16, 2024

Firdous2307 commented Oct 16, 2024

niccokunzmann commented Oct 22, 2024

		@@ -148,3 +148,16 @@ This section contains useful links for maintainers and collaborators:

		- `Future of icalendar, looking for maintainer #360 <https://github.com/collective/icalendar/discussions/360>`__
		- `Comment on the Plone tests running with icalendar <https://github.com/collective/icalendar/pull/447#issuecomment-1277643634>`__

	An "VEVENT" calendar component is a grouping of component
	A "VEVENT" calendar component is a grouping of component

	calendar. For example, it can be an activity; such as a one-hour
	calendar. For example, it can be an activity, such as a one-hour

	long, department meeting from 8:00 AM to 9:00 AM, tomorrow.
	long department meeting from 8:00 AM to 9:00 AM tomorrow.

	properties that represents an action-item or assignment. For
	properties that represents an action item or assignment. For

	an individual; such as "Prepare for the upcoming conference
	an individual, such as "Prepare for the upcoming conference

Add rfc documentation #730

Add rfc documentation #730

Conversation

Firdous2307 commented Oct 13, 2024 • edited by github-actions bot Loading

RFC 5545 Documentation Addition

Changes

Timezone Component

Note

Firdous2307 commented Oct 13, 2024

coveralls commented Oct 13, 2024

Pull Request Test Coverage Report for Build 11317751379

Details

💛 - Coveralls

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevepiercy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

niccokunzmann commented Oct 14, 2024

Firdous2307 commented Oct 15, 2024 • edited Loading

Firdous2307 commented Oct 15, 2024

niccokunzmann commented Oct 16, 2024

Firdous2307 commented Oct 16, 2024

niccokunzmann commented Oct 22, 2024

Firdous2307 commented Oct 13, 2024 •

edited by github-actions bot

Loading

Firdous2307 commented Oct 15, 2024 •

edited

Loading