Update metadata and packaging files (#23)

Author: mikeqfu

.readthedocs.yml

@@ -24,4 +24,4 @@ formats:
 # Optionally declare the Python requirements required to build the docs
 python:
   install:
-    - requirements: docs/source/rtd-req.txt
+    - requirements: docs/source/requirements.txt

README.md

@@ -1,11 +1,11 @@
 # PyRCS
 
-[![PyPI](https://img.shields.io/pypi/v/pyrcs)](https://pypi.org/project/pyrcs/)
-[![Python Version](https://img.shields.io/pypi/pyversions/pyrcs)](https://www.python.org/downloads/)
-[![Documentation Status](https://readthedocs.org/projects/pyrcs/badge/?version=latest)](https://pyrcs.readthedocs.io/en/latest/?badge=latest)
-[![License](https://img.shields.io/pypi/l/pyrcs)](https://github.com/mikeqfu/pyrcs/blob/master/LICENSE)
-[![Codacy Badge](https://app.codacy.com/project/badge/Grade/7369679225b14eaeb92ba40c12c339d5)](https://app.codacy.com/gh/mikeqfu/pyrcs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
-[![Zenodo](https://zenodo.org/badge/92501006.svg)](https://zenodo.org/badge/latestdoi/92501006)
+[![PyPI - Version](https://img.shields.io/pypi/v/pyrcs)](https://pypi.org/project/pyrcs/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pyrcs)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/github/license/mikeqfu/pyrcs)](https://github.com/mikeqfu/pyrcs/blob/master/LICENSE)
+[![Read the Docs - Documentation](https://readthedocs.org/projects/pyrcs/badge/?version=latest)](https://pyrcs.readthedocs.io/en/latest/?badge=latest)
+[![Codacy - Code Quality](https://app.codacy.com/project/badge/Grade/7369679225b14eaeb92ba40c12c339d5)](https://app.codacy.com/gh/mikeqfu/pyrcs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![DOI](https://zenodo.org/badge/92501006.svg)](https://zenodo.org/badge/latestdoi/92501006)
 
 PyRCS is an open-source Python package designed to simplify the collection and management of diverse codes used in different systems within the UK rail industry. It serves as a practical toolkit for researchers, practitioners, and individuals who frequently interact with the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website and work extensively with railway codes in the UK. Leveraging the capabilities of the Python programming language, PyRCS enables efficient access to and manipulation of railway code data, enhancing productivity and effectiveness in working with these codes.
 
@@ -35,24 +35,25 @@ For a concise guide on how to use PyRCS, check out the [Quick Start](https://pyr
 
 The complete PyRCS Documentation is available in [HTML](https://pyrcs.readthedocs.io/en/latest/) and [PDF](https://pyrcs.readthedocs.io/_/downloads/en/latest/pdf/) formats.
 
-It is hosted on [ReadTheDocs](https://readthedocs.org/projects/pyrcs/) and includes detailed usage examples.
+It is hosted on [Read the Docs](https://app.readthedocs.org/projects/pyrcs/), and the HTML version is also accessible via [GitHub Pages](https://mikeqfu.github.io/pyrcs/). The documentation includes detailed examples, tutorials and comprehensive references to help users get the most out of PyRCS. 
 
 ## Cite as
 
 Fu, Q. (2020). PyRCS: an open-source tool for collecting railway codes used in different UK rail industry systems. Zenodo. [doi:10.5281/zenodo.4026744](https://doi.org/10.5281/zenodo.4026744)
 
 ```bibtex
-@software{qian_fu_pyrcs_4026744,
-    author = {Qian Fu},
+@software{Fu_PyRCS_2020,
+    author = {Fu, Qian},
     title = {{PyRCS: An open-source tool for collecting railway codes used in different UK rail industry systems}},
     year = 2020,
     publisher = {Zenodo},
     doi = {10.5281/zenodo.4026744},
-    url = {https://doi.org/10.5281/zenodo.4026744}
+    license = {MIT},
+    url = {https://github.com/mikeqfu/pyrcs}
 }
 ```
 
-For specific version references of PyRCS, please refer to [Zenodo](https://zenodo.org/search?q=conceptrecid%3A%224026744%22&f=allversions%3Atrue&l=list&p=1&s=10&sort=version).
+For specific version references, please refer to [Zenodo](https://zenodo.org/search?q=conceptrecid%3A%224026744%22&f=allversions%3Atrue&l=list&p=1&s=10&sort=version).
 
 ## License
 

docs/source/conf.py

@@ -23,11 +23,6 @@
 release = version  # The full version, including alpha/beta/rc tags
 
 # == General configuration =========================================================================
-import inspect
-import requests
-import warnings
-import pyrcs
-
 extensions = [  # Sphinx extension module names, which can be named 'sphinx.ext.*' or custom ones:
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
@@ -47,13 +42,6 @@
     # "IPython.sphinxext.ipython_directive",
 ]
 
-# Validate URL for 'linkcode'
-main_url_ = f'https://github.com/mikeqfu/{__pkgname__}/blob'
-main_url = f'{main_url_}/{pyrcs.__version__}/{__pkgname__}'
-response = requests.get(main_url)
-if response.status_code == 404:
-    main_url = f"{main_url_}/master"
-
 
 def linkcode_resolve(domain, info):
     """
@@ -62,6 +50,18 @@ def linkcode_resolve(domain, info):
     (Adapted from https://github.com/pandas-dev/pandas/blob/main/doc/source/conf.py)
     """
 
+    import inspect
+    import requests
+    import warnings
+    import pyrcs
+
+    # Validate URL for 'linkcode'
+    main_url_ = f'https://github.com/mikeqfu/{__pkgname__}/blob'
+    main_url = f'{main_url_}/{pyrcs.__version__}/{__pkgname__}'
+    response = requests.get(main_url)
+    if response.status_code == 404:
+        main_url = f"{main_url_}/master"
+
     if domain != 'py' or not info['module']:
         return None
 
@@ -145,6 +145,7 @@ def linkcode_resolve(domain, info):
 # Automatically documented members are sorted by source order ('bysource'):
 autodoc_member_order = 'bysource'
 
+
 # == Options for HTML and HTMLHelp output ==========================================================
 html_theme = 'furo'  # The theme to use for HTML & HTML Help pages  # 'sphinx_rtd_theme'
 html_title = __project__
@@ -241,8 +242,8 @@ def __init__(self, **options):
 # Grouping the document tree into LaTeX files:
 latex_documents = [
     ('latexindex',  # source start file
-     __pkgname__ + '.tex',  # target name
-     __project__ + ' Documentation',  # title
+     f'{__pkgname__}.tex',  # target name
+     f'{__project__} Documentation',  # title
      __author__,  # author
      'manual',  # document class ['howto', 'manual', or own class]
      1  # toctree only

docs/source/index.rst

@@ -2,30 +2,34 @@
 PyRCS
 #####
 
-|PyPI| |Python| |Documentation| |License| |Codacy grade| |DOI|
+|PyPI - Version| |PyPI - Python Version| |Read the Docs - Documentation| |License| |Codacy - Code Quality| |DOI|
 
-.. |PyPI| image:: https://img.shields.io/pypi/v/pyrcs
-    :alt: PyPI - Release
+.. |PyPI - Version| image:: https://img.shields.io/pypi/v/pyrcs
+    :alt: PyPI - Version
     :target: https://pypi.org/project/pyrcs/
-.. |Python| image:: https://img.shields.io/pypi/pyversions/pyrcs
-    :alt: Python version
+.. |PyPI - Python Version| image:: https://img.shields.io/pypi/pyversions/pyrcs
+    :alt: PyPI - Python Version
     :target: https://www.python.org/downloads/
-.. |Documentation| image:: https://readthedocs.org/projects/pyrcs/badge/?version=latest
-    :alt: Documentation status
+.. |Read the Docs - Documentation| image:: https://img.shields.io/readthedocs/pyrcs?logo=readthedocs
+    :alt: Read the Docs - Documentation
     :target: https://pyrcs.readthedocs.io/en/latest/?badge=latest
-.. |License| image:: https://img.shields.io/pypi/l/pyrcs
+.. |License| image:: https://img.shields.io/github/license/mikeqfu/pyrcs
     :alt: License
     :target: https://github.com/mikeqfu/pyrcs/blob/master/LICENSE
-.. |Codacy grade| image:: https://app.codacy.com/project/badge/Grade/7369679225b14eaeb92ba40c12c339d5
-    :alt: Codacy grade (Code quality)
+.. |Codacy - Code Quality| image:: https://app.codacy.com/project/badge/Grade/7369679225b14eaeb92ba40c12c339d5
+    :alt: Codacy - Code Quality
     :target: https://www.codacy.com/gh/mikeqfu/pyrcs/dashboard?utm_source=github.com&utm_medium=referral&utm_content=mikeqfu/pyrcs&utm_campaign=Badge_Grade
-.. |DOI| image:: https://zenodo.org/badge/92501006.svg
-    :alt: Zenodo - DOI
-    :target: https://zenodo.org/badge/latestdoi/92501006
+.. |DOI| image:: https://img.shields.io/badge/10.5281%2Fzenodo.4026744-blue?label=doi
+    :alt: DOI
+    :target: https://doi.org/10.5281/zenodo.4026744
 
-| **Author**: Qian Fu
+| **Author**: Qian Fu |ORCID|
 | **Email**: [email protected]
 
+.. |ORCID| image:: https://info.orcid.org/wp-content/uploads/2019/11/orcid_16x16.png
+    :alt: ORCID
+    :target: https://orcid.org/0000-0002-6502-9934
+
 PyRCS is an open-source Python package designed to simplify the collection and management of diverse codes used in different systems within the UK rail industry. It serves as a practical toolkit for researchers, practitioners, and individuals who frequently interact with the `Railway Codes <http://www.railwaycodes.org.uk/index.shtml>`_ website and work extensively with railway codes in the UK. Leveraging the capabilities of the Python programming language, PyRCS enables efficient access to and manipulation of railway code data, enhancing productivity and effectiveness in working with these codes.
 
 During :doc:`installation`, PyRCS includes a set of pre-packaged data. When users request data from a specific category listed on the `Railway Codes <http://www.railwaycodes.org.uk/index.shtml>`_ website, PyRCS automatically loads the corresponding pre-packaged data for that category by default. Additionally, it provides functionality that enables direct access to the latest data from the data source website, ensuring users can stay updated with the most current information. Furthermore, PyRCS users can conveniently update the relevant pre-packaged data, keeping their data resources synchronized with the latest developments.

docs/source/installation.rst

@@ -1,5 +1,3 @@
-.. _pyrcs-installation:
-
 ============
 Installation
 ============

docs/source/modules.rst

@@ -1,5 +1,3 @@
-.. _pyrcs-modules:
-
 =======
 Modules
 =======

docs/source/quick-start.rst

@@ -47,12 +47,12 @@ Alternatively, we can create the instance using the :class:`~pyrcs.collector.Lin
     - The instance ``ld`` encompasses all classes within the `line data`_ category.
     - ``lid_`` is equivalent to ``lid``.
 
-.. _quickstart-location-identifiers-given-initial:
+.. _quickstart-location-identifiers-by-initial-letter:
 
-Location identifiers for a specific initial letter
---------------------------------------------------
+Location identifiers by initial letter
+--------------------------------------
 
-We can retrieve codes (in `pandas.DataFrame`_ format) for all locations starting with a specific letter using the :meth:`LocationIdentifiers.collect_codes_by_initial()<pyrcs.line_data.LocationIdentifiers.collect_codes_by_initial>` method. This method is case-insensitive. For example, to get the codes for locations whose names begin with the letter ``'A'`` (or ``'a'``):
+We can retrieve codes (in `pandas.DataFrame`_ format) for all locations starting with a specific letter using the :meth:`LocationIdentifiers.collect_codes_by_initial()<pyrcs.line_data.LocationIdentifiers.collect_codes_by_initial>` method. This input value for the parameter is case-insensitive. For example, to get the codes for locations whose names begin with the letter ``'A'`` (or ``'a'``):
 
 .. code-block:: python
 
@@ -92,7 +92,7 @@ A snapshot of the data contained in ``loc_a_codes`` is demonstrated below:
     >>> print("Last updated date: {}".format(loc_a_codes['Last updated date']))
     Last updated date: 2024-08-24
 
-.. _quickstart-all-location-identifiers:
+.. _quickstart-all-available-location-identifiers:
 
 All available location identifiers
 ----------------------------------
@@ -222,7 +222,7 @@ The ``elrs_a_codes`` object is a dictionary with the following *keys*:
 
 The corresponding *values* are:
 
--  ``elrs_a_codes['A']`` - Data for ELRs that begin with ``'A'`` (referring to the table presented on the web page `ELRs beginning with A`_).
+-  ``elrs_a_codes['A']`` - Data for ELRs that begin with ``'A'``, referring to the table presented on the `ELRs beginning with A`_ web page.
 -  ``elrs_a_codes['Last updated date']`` - The date when the `ELRs beginning with A`_ web page was last updated.
 
 Here is a snapshot of the data contained in ``elrs_a_codes``:
@@ -260,7 +260,7 @@ Similarly, ``elrs_codes`` is a dictionary with the following *keys*:
 
 The corresponding *values* are:
 
--  ``elrs_codes['ELRs and mileages']`` - Codes for all available ELRs (with the initial letters ranging from ``'A'`` to ``'Z'``);
+-  ``elrs_codes['ELRs and mileages']`` - Codes for all available ELRs (with the initial letters ranging from ``'A'`` to ``'Z'``).
 -  ``elrs_codes['Latest update date']`` - The most recent update date among all the ELR data.
 
 Here is a snapshot of the data contained in ``elrs_codes``:
@@ -279,7 +279,7 @@ Here is a snapshot of the data contained in ``elrs_codes``:
     4579  ZZZ9  Dummy ELR for demonstrations and testing  ...   n/a
     [5 rows x 5 columns]
 
-.. _quickstart-mileage-files-given-elr:
+.. _quickstart-mileage-file-of-a-given-elr:
 
 Mileage file of a given ELR
 ---------------------------
@@ -296,7 +296,7 @@ For example, to get the `mileage file for 'AAM'`_:
     >>> list(amm_mileage_file.keys())
     ['ELR', 'Line', 'Sub-Line', 'Mileage', 'Notes']
 
-The ``amm_mileage_file`` is also a dictionary and has the following *keys*:
+The ``amm_mileage_file`` object is also a dictionary and has the following *keys*:
 
 -  ``'ELR'``
 -  ``'Line'``
@@ -364,10 +364,10 @@ Alternatively, we can also create the instance by using the :class:`~pyrcs.colle
     - The instance ``stn`` encompasses all classes within the `other assets`_ category.
     - ``stn_`` is equivalent to ``stn``.
 
-.. _quickstart-railway-station-locations-given-initial:
+.. _quickstart-railway-stations-by-initial-letter:
 
-Railway station locations given a specific initial letter
----------------------------------------------------------
+Railway stations by initial letter
+----------------------------------
 
 We can obtain railway station data based on the first letter (e.g. ``'A'`` or ``'Z'``) of the station's name using the :meth:`Stations.collect_locations_by_initial()<pyrcs.other_assets.Stations.collect_locations_by_initial>` method. For example, to get data for stations starting with ``'A'``:
 
@@ -429,10 +429,10 @@ Here is a snapshot of the data contained in ``stn_loc_a``:
     >>> print("Last updated date: {}".format(stn_loc_a_codes['Last updated date']))
     Last updated date: 2024-09-23
 
-.. _quickstart-all-railway-station-locations:
+.. _quickstart-all-available-railway-stations:
 
-All available railway station locations
----------------------------------------
+All available railway stations
+------------------------------
 
 To retrieve data for all railway stations available in the `other assets`_ category, we can use the :meth:`Stations.fetch_locations()<pyrcs.other_assets.Stations.fetch_locations>` method:
 
@@ -451,7 +451,7 @@ The dictionary ``stn_loc_codes`` includes the following *keys*:
 
 The corresponding *values* are:
 
--  ``stn_loc_codes['Mileages, operators and grid coordinates']`` - Data for all railway stations, with the initial letters ranging from ``'A'`` to ``'Z'``;
+-  ``stn_loc_codes['Mileages, operators and grid coordinates']`` - Data for all railway stations, with the initial letters ranging from ``'A'`` to ``'Z'``.
 -  ``stn_loc_codes['Latest update date']`` - The most recent update date among all the station data.
 
 Here is a snapshot of the data contained in ``stn_loc_codes``:

docs/source/rtd-req.txt renamed to docs/source/requirements.txt

@@ -6,9 +6,12 @@
 import json
 import pkgutil
 
-from .collector import *
+from .collector import LineData, OtherAssets
+from .line_data import Bridges, ELRMileages, Electrification, LOR, LineNames, LocationIdentifiers, \
+    TrackDiagrams
+from .other_assets import Depots, Features, SignalBoxes, Stations, Tunnels, Viaducts
 
-metadata = json.loads(pkgutil.get_data(__name__, "data/metadata").decode())
+metadata = json.loads(pkgutil.get_data(__name__, "data/.metadata").decode())
 
 __project__ = metadata['Project']
 __pkgname__ = metadata['Package']

pyrcs/__init__.py

@@ -9,15 +9,14 @@
 """
 
 import time
-import urllib.parse
 
 from pyhelpers.ops import confirmed
 
-from .line_data import (Bridges, ELRMileages, Electrification, LOR, LineNames, LocationIdentifiers,
-                        TrackDiagrams)
+from .line_data import Bridges, ELRMileages, Electrification, LOR, LineNames, LocationIdentifiers, \
+    TrackDiagrams
 from .other_assets import Depots, Features, SignalBoxes, Stations, Tunnels, Viaducts
 from .parser import get_category_menu
-from .utils import home_page_url, is_home_connectable, print_conn_err, print_inst_conn_err
+from .utils import is_home_connectable, print_conn_err, print_inst_conn_err
 
 
 class LineData:
@@ -31,10 +30,6 @@ class LineData:
     #: The name of the data.
     NAME: str = 'Line data'
 
-    #: The URL of the main web page for the data.
-    URL: str = urllib.parse.urljoin(
-        home_page_url(), '{}menu.shtm'.format(NAME.lower().replace(' ', '')))
-
     def __init__(self, update=False, verbose=True):
         """
         :param update: Whether to check for updates to the catalogue; defaults to ``False``.
@@ -101,7 +96,7 @@ def __init__(self, update=False, verbose=True):
         else:
             self.connected = True
 
-        self.catalogue = get_category_menu(url=self.URL, update=update, confirmation_required=False)
+        self.catalogue = get_category_menu(self.NAME, update=update, confirmation_required=False)
 
         # Relevant classes
         self.ELRMileages = ELRMileages(update=update, verbose=False)
@@ -205,10 +200,6 @@ class OtherAssets:
     #: The name of the data.
     NAME: str = 'Other assets'
 
-    #: The URL of the main web page for the data.
-    URL: str = urllib.parse.urljoin(
-        home_page_url(), '{}menu.shtm'.format(NAME.lower().replace(' ', '')))
-
     def __init__(self, update=False, verbose=True):
         """
         :param update: Whether to check for updates to the catalogue; defaults to ``False``.
@@ -271,7 +262,7 @@ def __init__(self, update=False, verbose=True):
         else:
             self.connected = True
 
-        self.catalogue = get_category_menu(url=self.URL, update=update, confirmation_required=False)
+        self.catalogue = get_category_menu(self.NAME, update=update, confirmation_required=False)
 
         # Relevant classes
         self.SignalBoxes = SignalBoxes(update=update, verbose=False)

pyrcs/collector.py

@@ -123,9 +123,9 @@ def _collect_notes(h3):
             while h3_ == h3:
                 notes_2 = get_hypertext(hypertext_tag=next_p, hyperlink_tag_name='a')
                 if notes_2:
-                    notes_2 = notes_2. \
-                        replace(' Section codes known at present are:', ''). \
-                        replace('Known prefixes are:', ' ')
+                    notes_2 = notes_2.replace(
+                        ' Section codes known at present are:', '').replace(
+                        'Known prefixes are:', ' ')
                     notes_.append(notes_2)
 
                 next_p = next_p.find_next('p')