From e00d1d39badb7aa3595ca1c8a5a8ee4195df6910 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 19:16:00 -0700 Subject: [PATCH 1/3] Add docs for live HTML preview of documentation and clean up. - Use shell instead of bash as a universal shell. - Use pycon for Python console commands. - Remove command prompts from shell commands to make them easier to copy and have neutral shell. - Remove `http.server` option as it's been replaced by `make livehtml`. Closes #673 --- docs/install.rst | 61 ++++++++++++++++++++++++------------------------ 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 76faa24d..5bb46078 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,14 +1,18 @@ Installing iCalendar ==================== -To install the icalendar package, use:: +To install the icalendar package, use: - pip install icalendar +.. code-block:: shell + + pip install icalendar If installation is successful, you will be able to import the iCalendar -package, like this:: +package, like this: + +.. code-block:: pycon - >>> import icalendar + >>> import icalendar Development Setup ----------------- @@ -19,7 +23,7 @@ using Git. You can `fork `_ the project first and clone your fork, too. -.. code-block:: bash +.. code-block:: shell git clone https://github.com/collective/icalendar.git cd icalendar @@ -39,7 +43,7 @@ Install Tox First, install `tox `_.. -.. code-block:: bash +.. code-block:: shell pip install tox @@ -53,7 +57,7 @@ Running Tests To run all tests in all environments, simply run ``tox`` -.. code-block:: bash +.. code-block:: shell tox @@ -63,7 +67,7 @@ Have a look at the `documentation `__. This is how you can run ``tox`` with Python 3.9: -.. code-block:: bash +.. code-block:: shell tox -e py39 @@ -73,7 +77,7 @@ Accessing a ``tox`` environment If you like to enter a specific tox environment, you can do this: -.. code-block:: bash +.. code-block:: shell source .tox/py39/bin/activate @@ -93,7 +97,7 @@ this section explains how to do it. You can install the local copy of ``icalendar`` with ``pip`` like this: -.. code-block:: bash +.. code-block:: shell cd icalendar python -m pip install -e . @@ -106,7 +110,7 @@ manually setup ``icalendar`` like this. Try it out: -.. code-block:: python +.. code-block:: pycon Python 3.9.5 (default, Nov 23 2021, 15:27:38) Type "help", "copyright", "credits" or "license" for more information. @@ -114,32 +118,29 @@ Try it out: >>> icalendar.__version__ '5.0.13' -Building the documentation --------------------------- +Build the documentation +----------------------- + +To build the documentation, follow these steps: -To build the documentation follow these steps: +.. code-block:: shell -.. code-block:: bash + source .tox/py311/bin/activate + pip install -r requirements_docs.txt + cd docs + make html - $ source .tox/py39/bin/activate - $ pip install -r requirements_docs.txt - $ cd docs - $ make html +You can now open the output from ``_build/html/index.html``. -You can now open the output from ``_build/html/index.html``. To build the -presentation-version use ``make presentation`` instead of ``make html``. You -can open the presentation at ``presentation/index.html``. +To build the documentation, view it in a web browser, and automatically reload changes while you edit documentation, use ``make livehtml`` instead of ``make html``. +Then open a web browser at `http://127.0.0.1:8050 `_. + +To build the presentation-version use ``make presentation`` instead of ``make html``. +You can open the presentation at ``presentation/index.html``. You can also use ``tox`` to build the documentation: -.. code-block:: bash +.. code-block:: shell cd icalendar tox -e docs - -If you would like to serve the documentation and access it from your browser, -you can run the HTTP server: - -.. code-block:: bash - - python3 -m http.server -d docs/_build/html/ From 54a866f93f74bba8143c8d79f2b097972301ffcf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 19:17:49 -0700 Subject: [PATCH 2/3] change log --- CHANGES.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES.rst b/CHANGES.rst index 87e4f5c9..e36af6b0 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -62,6 +62,7 @@ New features: - Test compatibility with Python 3.12 - Add function ``icalendar.use_pytz()``. - Add `sphinx-autobuild` for `livehtml` Makefile target. +- Add documentation of live HTML preview of documentation and clean up of ``install.rst``. Bug fixes: From 8581d355d6250b27ca9d8708d7c206f66cee73e4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 2 Jul 2024 21:38:28 -0700 Subject: [PATCH 3/3] Use code blocks instead of inline --- docs/install.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 5bb46078..517d0a57 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -132,10 +132,20 @@ To build the documentation, follow these steps: You can now open the output from ``_build/html/index.html``. -To build the documentation, view it in a web browser, and automatically reload changes while you edit documentation, use ``make livehtml`` instead of ``make html``. +To build the documentation, view it in a web browser, and automatically reload changes while you edit documentation, use the following command. + +.. code-block:: shell + + make livehtml + Then open a web browser at `http://127.0.0.1:8050 `_. -To build the presentation-version use ``make presentation`` instead of ``make html``. +To build the presentation-version use the following command. + +.. code-block:: shell + + make presentation + You can open the presentation at ``presentation/index.html``. You can also use ``tox`` to build the documentation: