Improved documentation by adding code comments and ensuring consistency

[Rohit1240]

…cy in code blocks

This PR improves documentation by:

• Ensuring consistency in code block formatting
• Adding helpful comments to code examples for better understanding

Closes issue

Replace ISSUE_NUMBER with the issue number that your pull request fixes. Then GitHub will link and automatically close the related issue.

• Closes #ISSUE_NUMBER

Description

Write a description of the fixes or improvements.

Checklist

• I've added a change log entry to CHANGES.rst.
• I've added or updated tests if applicable.
• I've run and ensured all tests pass locally by following Run tests.
• I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary.

Additional information

Upload screenshots, videos, links to documentation, or any other relevant information.

---

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

[read-the-docs-community]

Documentation build overview

📚 icalendar | 🛠️ Build #32486150 | 📁 Comparing e78cce2 against latest (0e7c6df)

  🔍 Preview build  

2 files changed

± 404.html
± how-to/usage.html

[Rohit1240]

Hi, I worked on improving documentation by fixing references to Python objects using fully qualified names.
Additionally, I enhanced readability by adding comments to code examples and improving formatting consistency.
For example, I replaced incomplete references like :meth:add() with fully qualified names such as :meth:icalendar.cal.component.Component.add.
Please let me know if any changes are needed. This is my first open source contribution.

[niccokunzmann]

Hi,

thanks for your contribution and time. We require to log the changes in the changelog file. Also, have a look at the failing tests. They need to run. If you have questiins, please ask us!

[stevepiercy]

Thanks for your contribution! You caught a few things that were missed, some for over two decades. Would you please take a look at my suggestions?

[stevepiercy]

Inline comments should have a minimum of two spaces after the line of code.

Suggested change

	>>> cal = Calendar() # create a calendar object
	>>> cal.add("dtstart", datetime(2005,4,4,8,0,0)) # set start date
	>>> cal = Calendar() # create a calendar object
	>>> cal.add("dtstart", datetime(2005,4,4,8,0,0)) # set start date

[stevepiercy]

This suggestion was omitted.

[stevepiercy]

Regarding the failing test, this is due to fixing the Sphinx directive, changing it from code to code-block, so that the test actually runs for the first time. The output in the documentation should be updated to match the actual Python console output.

[niccokunzmann]

Hi, we created a new release, please move your edits in CHANGES.rst to the new section.

[stevepiercy]

The failing tests are due to fixing the Sphinx directive, changing it from code to code-block, so that the test actually runs for the first time. The output in the documentation should be updated to match the actual Python console output. See https://icalendar.readthedocs.io/en/stable/contribute/documentation/build-check.html#test-code-snippets-and-docstrings.

Also please update your branch against main, then move the change log entry under the unreleased section.

[stevepiercy]

This suggestion was omitted.

[stevepiercy]

@Rohit1240 there are several instances that need to be fixed. Would you please take care? Thank you!

[stevepiercy]

This comments out the code-block directive, so the ensuing code block is not rendered correctly. Please change this and all other instances as shown.

Suggested change

	.. .. code-block:: pycon
	.. code-block:: pycon

[stevepiercy]

Alternatively, rebase your branch on main after #1412 is merged. Thank you!

[stevepiercy]

@Rohit1240 also, would you please edit your description from Closes #ISSUE_NUMBER to Refs #626? Thank you!