Backticks in all docstrings

Author: nils-herrmann

pybliometrics/scopus/abstract_citation.py

@@ -14,7 +14,7 @@ def authors(self) -> Optional[List[Optional[List[Optional[NamedTuple]]]]]:
         """A list of lists of namedtuples storing author information,
         where each namedtuple corresponds to one author and each sub-list to
         one document.
-        The information in each namedtuple is (name surname initials id url).
+        The information in each namedtuple is `(name surname initials id url)`.
         All entries are strings.
         """
         outer = []
@@ -24,7 +24,8 @@ def authors(self) -> Optional[List[Optional[List[Optional[NamedTuple]]]]]:
             inner = []
             for author in doc.get('author', []):
                 author = {k.split(":", 1)[-1]: v for k, v in author.items()}
-                new = auth(name=author.get('index-name'), id=author['authid'],
+                new = auth(name=author.get('index-name'),
+                           id=author['authid'],
                            surname=author.get('surname'),
                            initials=author.get('initials'),
                            url=author.get('author-url'))
@@ -199,17 +200,17 @@ def __init__(self,
                  citation: Optional[str] = None,
                  **kwds: str
                  ) -> None:
-        """Interaction witht the Citation Overview API.
+        """Interaction with the Citation Overview API.
 
-        :param identifier: Up to 25 identifiers for which  to look up
+        :param identifier: Up to 25 identifiers for which to look up
                            citations.  Must be Scopus IDs, DOIs, PIIs or
                            Pubmed IDs.
         :param start: The first year for which the citation count should
                       be loaded.
         :param end: The last year for which the citation count should be
                     loaded. Defaults to the current year.
         :param id_type: The type of the IDs provided in `identifier`.  Must be
-                        one of "scopus_id", "doi", "pii", "pubmed_id".
+                        one of `"scopus_id", "doi", "pii", "pubmed_id"`.
         :param eid: (deprecated) The Scopus ID of the abstract - will be
                     removed in a future release: Instead use param `scopus_id`
                     after stripping the part until the second hyphen.  If you
@@ -220,7 +221,7 @@ def __init__(self,
                         number of days since last modification exceeds that value.
         :param citation: Allows for the exclusion of self-citations or those
                          by books.  If `None`, will count all citations.
-                         Allowed values: None, exclude-self, exclude-books
+                         Allowed values: `None, exclude-self, exclude-books`
         :param kwds: Keywords passed on as query parameters.  Must contain
                      fields and values mentioned in the API specification at
                      https://dev.elsevier.com/documentation/AbstractCitationAPI.wadl.

pybliometrics/scopus/abstract_retrieval.py

@@ -18,7 +18,7 @@ def abstract(self) -> Optional[str]:
     @property
     def affiliation(self) -> Optional[List[NamedTuple]]:
         """A list of namedtuples representing listed affiliations in
-        the form (id, name, city, country).
+        the form `(id, name, city, country)`.
         """
         out = []
         aff = namedtuple('Affiliation', 'id name city country')
@@ -50,10 +50,10 @@ def authkeywords(self) -> Optional[List[str]]:
     @property
     def authorgroup(self) -> Optional[List[NamedTuple]]:
         """A list of namedtuples representing the article's authors organized
-        by affiliation, in the form (affiliation_id, dptid, organization,
+        by affiliation, in the form `(affiliation_id, dptid, organization,
         city, postalcode, addresspart, country, collaboration, auid, orcid,
-        indexed_name, surname, given_name).
-        If "given_name" is not present, fall back to initials.
+        indexed_name, surname, given_name)`.
+        If `given_name` is not present, fall back to initials.
         Note: Affiliation information might be missing or mal-assigned even
         when it looks correct in the web view.  In this case please request
         a correction.  It is generally missing for collaborations.
@@ -111,8 +111,8 @@ def authorgroup(self) -> Optional[List[NamedTuple]]:
     @property
     def authors(self) -> Optional[List[NamedTuple]]:
         """A list of namedtuples representing the article's authors, in the
-        form (auid, indexed_name, surname, given_name, affiliation).  In case
-        multiple affiliation IDs are given, they are joined on ";".
+        form `(auid, indexed_name, surname, given_name, affiliation)`.  In case
+        multiple affiliation IDs are given, they are joined on `";"`.
         Note: The affiliation referred to here is what Scopus' algorithm
         determined as the main affiliation.  Property `authorgroup` provides
         all affiliations.
@@ -146,8 +146,8 @@ def citedby_link(self) -> str:
     @property
     def chemicals(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples representing chemical entities in the form
-        (source, chemical_name, cas_registry_number).  In case multiple
-        numbers given, they are joined on ";".
+        `(source, chemical_name, cas_registry_number)`.  In case multiple
+        numbers given, they are joined on `";"`.
         """
         path = ['enhancement', 'chemicalgroup', 'chemicals']
         items = listify(chained_get(self._head, path, []))
@@ -209,7 +209,7 @@ def confsponsor(self) -> Optional[Union[List[str], str]]:
     @property
     def contributor_group(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples representing contributors compiled by Scopus,
-        in the form (given_name, initials, surname, indexed_name, role).
+        in the form `(given_name, initials, surname, indexed_name, role)`.
         """
         path = ['source', 'contributor-group']
         items = listify(chained_get(self._head, path, []))
@@ -240,8 +240,8 @@ def copyright_type(self) -> str:
     @property
     def correspondence(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples representing the authors to whom correspondence
-        should be addressed, in the form (surname, initials, organization,
-        country, city_group). Multiple organziations are joined on semicolon.
+        should be addressed, in the form ´(surname, initials, organization,
+        country, city_group)´. Multiple organziations are joined on semicolon.
         """
         fields = 'surname initials organization country city_group'
         auth = namedtuple('Correspondence', fields)
@@ -310,7 +310,7 @@ def endingPage(self) -> Optional[str]:
     @property
     def funding(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples parsed funding information in the form
-        (agency, agency_id, string, funding_id, acronym, country).
+        `(agency, agency_id, string, funding_id, acronym, country)`.
         """
 
         def _get_funding_id(f_dict: dict) -> list:
@@ -343,7 +343,7 @@ def funding_text(self) -> Optional[str]:
 
     @property
     def isbn(self) -> Optional[Tuple[str, ...]]:
-        """ISBNs Optional[str] to publicationName as tuple of variying length,
+        """ISBNs `Optional[str]` to publicationName as tuple of variying length,
         (e.g. ISBN-10 or ISBN-13)."""
         isbns = listify(chained_get(self._head, ['source', 'isbn'], []))
         if len(isbns) == 0:
@@ -353,7 +353,7 @@ def isbn(self) -> Optional[Tuple[str, ...]]:
 
     @property
     def issn(self) -> Optional[NamedTuple]:
-        """Namedtuple in the form (print electronic).
+        """Namedtuple in the form `(print electronic)`.
         Note: If the source has an E-ISSN, the META view will return None.
         Use FULL view instead.
         """
@@ -495,9 +495,9 @@ def refcount(self) -> Optional[int]:
     @property
     def references(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples representing references listed in the document,
-        in the form (position, id, doi, title, authors, authors_auid,
+        in the form `(position, id, doi, title, authors, authors_auid,
         authors_affiliationid, sourcetitle, publicationyear, coverDate, volume,
-        issue, first, last, citedbycount, type, text, fulltext).
+        issue, first, last, citedbycount, type, text, fulltext)`.
 
         `position` is the number at which the reference appears in the
         document, `id` is the Scopus ID of the referenced document (EID
@@ -587,7 +587,7 @@ def self_link(self) -> str:
     @property
     def sequencebank(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples representing biological entities defined or
-        mentioned in the text, in the form (name, sequence_number, type).
+        mentioned in the text, in the form `(name, sequence_number, type)`.
         """
         path = ['enhancement', 'sequencebanks', 'sequencebank']
         items = listify(chained_get(self._head, path, []))
@@ -634,7 +634,7 @@ def startingPage(self) -> Optional[str]:
     @property
     def subject_areas(self) -> Optional[List[NamedTuple]]:
         """List of namedtuples containing subject areas of the article
-        in the form (area abbreviation code).
+        in the form `(area abbreviation code)`.
         Note: Requires the FULL view of the article.
         """
         area = namedtuple('Area', 'area abbreviation code')

pybliometrics/scopus/affiliation_retrieval.py

@@ -57,7 +57,7 @@ def identifier(self) -> int:
 
     @property
     def name_variants(self) -> List[NamedTuple]:
-        """A list of namedtuples representing variants of the affiliation name
+        """A list of namedtuples representing variants of the `affiliation_name`
         with number of documents referring to this variant.
         """
         variant = namedtuple('Variant', 'name doc_count')
@@ -73,7 +73,7 @@ def org_domain(self) -> Optional[str]:
     @property
     def org_type(self) -> Optional[str]:
         """Type of the affiliation.  Requires the STANDARD view and only
-        present if profile is org profile.
+        present if `profile` is `org profile`.
         """
         return self._profile.get('org-type')
 
@@ -138,10 +138,10 @@ def __init__(self,
                         If int is passed, cached file will be refreshed if the
                         number of days since last modification exceeds that value.
         :param view: The view of the file that should be downloaded.  Allowed
-                     values: LIGHT, STANDARD, where STANDARD includes all
-                     information of the LIGHT view.  For details see
+                     values: `LIGHT`, `STANDARD`, where `STANDARD` includes all
+                     information of the `LIGHT` view.  For details see
                      https://dev.elsevier.com/sc_affil_retrieval_views.html.
-                     Note: Neither the BASIC view nor DOCUMENTS or AUTHORS
+                     Note: Neither the `BASIC` view nor `DOCUMENTS` or `AUTHORS`
                      views are active, although documented.
         :param kwds: Keywords passed on as query parameters.  Must contain
                      fields and values mentioned in the API specification at

pybliometrics/scopus/affiliation_search.py

@@ -11,16 +11,16 @@ class AffiliationSearch(Search):
     def affiliations(self) -> Optional[List[NamedTuple]]:
         """A list of namedtuples storing affiliation information,
         where each namedtuple corresponds to one affiliation.
-        The information in each namedtuple is (eid name variant documents city
-        country parent).
+        The information in each namedtuple is `(eid name variant documents city
+        country parent)`.
 
-        All entries are strings or None.  Field "variant" combines variants
-        of names with a semicolon.
+        All entries are `strings` or `None`.  Field `variant` combines variants
+        of names with a `";"`.
 
         Raises
         ------
-        ValueError
-            If the elements provided in integrity_fields do not match the
+        `ValueError`
+            If the elements provided in `integrity_fields` do not match the
             actual field names (listed above).
         """
         # Initiate namedtuple with ordered list of fields
@@ -63,16 +63,16 @@ def __init__(self,
         :param download: Whether to download results (if they have not been
                          cached).
         :param integrity_fields: Names of fields whose completeness should
-                                 be checked.  AffiliationSearch will perform
+                                 be checked.  `AffiliationSearch` will perform
                                  the action specified in `integrity_action`
                                  if elements in these fields are missing.
                                  This helps avoiding idiosynchratically missing
                                  elements that should always be present
                                  (e.g. EID or name).
         :param integrity_action: What to do in case integrity of provided fields
                                  cannot be verified.  Possible actions:
-                                 - "raise": Raise an AttributeError
-                                 - "warn": Raise a UserWarning
+                                 - `"raise"`: Raise an AttributeError
+                                 - `"warn"`: Raise a UserWarning
         :param count: (deprecated) The number of entries to be displayed at
                       once.  A smaller number means more queries with each
                       query having fewer results.
@@ -82,12 +82,12 @@ def __init__(self,
 
         Raises
         ------
-        ScopusQueryError
+        `ScopusQueryError`
             If the number of search results exceeds 5000, which is the API's
             maximum number of results returned.  The error prevents the
             download attempt and avoids making use of your API key.
 
-        ValueError
+        `ValueError`
             If any of the parameters `integrity_action` or `refresh` is not
             one of the allowed values.