ADD: examples to the docs

docs/core.md

@@ -2,42 +2,122 @@
 
 How to install the package: [installation](installation.md)
 
-### Basics
+### Basics Usage
 
-Here's a quick snippet to get info on the author with the name `John Wilbanks`_. :
+#### A quick snippet to get info on the author 
 
-    >>> import orcidpyclient
-    >>> #retrieve john's profile from his ORCID
-    >>> orcid_res = orcidpyclient.get('0000-0002-4510-0385')
-    >>> print (orcid_res.family_name)
-    wilbanks
+The name of the author ```John Wilbanks```
 
-What if you'd like to see an author's works or areas of interest? :
+```python
+import orcidpyclient
+orcid_res = orcidpyclient.get('0000-0002-4510-0385')
+print (orcid_res.family_name)
+```
 
-    >>> print (orcid_res.keywords)
-    []
-    >>> print (orcid_res.publications)
-    []
+Expected output:
+```bash
+wilbanks
+```
 
-Try another author with a different ORCID:
+#### See an author's works or areas of interest
 
-    >>> author = orcidpyclient.get('0000-0001-8855-5569')
-    >>> print (author.keywords)
-    [u'computer science', u' bioinformatics', u' computational biology']
-    >>> print (author.publications[0])
-    <Publication "A note about norbert wiener and his contribution to harmonic analysis and tauberian theorems">
+```python
+import orcidpyclient
+orcid_res = orcidpyclient.get('0000-0002-4510-0385')
+print(orcid_res.keywords)
+print(orcid_res.publications)
+```
+#### Iterate over keywords
 
-Read about author's contributions:
+```python
+import orcidpyclient
+orcid_res = orcidpyclient.get('0000-0002-4510-0385')
+for key_word in orcid_res.keywords:
+    print (key_word)
+```
 
-    >>> print (author.publications[0].url)
-    http://www.scopus.com/inward/record.url?eid=2-s2.0-67650513866&partnerID=MN8TOARS
+#### Trying different author with a different ORCID
 
-### Searching
+```python
+import orcidpyclient
+author = orcidpyclient.get('0000-0001-8855-5569')
+print (author.keywords)
+print (author.publications[0])
+```
+
+Expected output:
+
+```bash
+$ [u'computer science', u' bioinformatics', u' computational biology']
+$ <Publication "A note about norbert wiener and his contribution to harmonic analysis and tauberian theorems">
+```
+
+#### Getting infos on author's contributions:
+
+```python
+import orcidpyclient
+author = orcidpyclient.get('0000-0001-8855-5569')
+print(author.publications[0].url)
+````
+
+Expected output:
+```bash
+$ http://www.scopus.com/inward/record.url?eid=2-s2.0-67650513866&partnerID=MN8TOARS
+```
+
+#### Different ways to run orcid search (e.g., by author's name)
+
+##### Search for an author
 
 If you'd rather search for authors, try ORCID's search functionality using its
 [API specification](https://members.orcid.org/api/tutorial/search-orcid-registry) :
 
-    >>> #do a simple author search for john
-    >>> authors = orcidpyclient.search('family-name:wilbanks+AND+given-names:john')
-    >>> print (next(authors).family_name)
-    wilbanks
+```python
+import orcidpyclient
+authors = orcidpyclient.search('family-name:wilbanks+AND+given-names:john')
+print (next(authors).family_name)
+```
+Expected output:
+```bash
+$ wilbanks
+```
+
+##### Search for an author with no ORCID
+
+```python
+import orcidpyclient
+authors = orcidpyclient.search('family-name:wilbanksTestName+AND+given-names:john')
+
+try:
+    first = next(authors)
+except StopIteration as ex:
+    raise Exception('No authors found')
+
+print(first.family_name)
+for author in authors:
+    print(author.family_name)
+```
+
+##### Search for an author with empty family name
+
+```python
+import orcidpyclient
+
+def get_affiliation(orcid:str):
+    """Gets affiliation of the"""
+
+    author = pyorcid.get(orcid)
+    print(f'Educations   : {author.educations}')
+    print(f'Employments  : {author.employments}')
+    print(f'Affiliations : {author.affiliations}')
+
+def empty_family_name():
+    """"Search for an author with empty family name"""
+
+    authors = import orcidpyclient.search('family-name:wilbanks&start=0&rows=3', verbose=False)
+    for author in authors:
+        print(f'Author: {author}')
+        get_affiliation(orcid = author.orcid)
+
+empty_family_name()
+```

docs/examples.md

@@ -0,0 +1,22 @@
+## Examples
+
+**Ready to run** examples showing how to use **orcidpyclient** Python package.
+
+#### Script to extract BibTeX from the ORCID
+
+* Script extracts bibtex from the ORCID:  [extracting_bibtex.py](examples/extracting_bibtex.py)
+
+#### Script to convert BibTeX from the ORCID to HTML
+
+* Script to convert BibTeX from the ORCID to HTML: [orcid_bibtex_to_html.py](examples/orcid_bibtex_to_html.py)
+* Additional information
+	+ iterates through the list or ID's, extracts ORCID, creates bat file to compile bibtex into HTMLs with help of JabRef
+		- List should be in the python dict format, here is the example (I created file 'orcid-list.json')
+		```
+		[
+		 { 'John Wilbanks' : '0000-0002-4510-0385'},
+        ]
+		```
+    + **NOTE**: To make in run on Mac OS, it's better if you will copy JabRef into the 'generated' folder directly
+
+

docs/examples/.gitignore

@@ -0,0 +1,15 @@
+#extentions
+*.pyc
+*.txt
+*.json
+*.log
+
+# folders
+*generated/
+
+# files
+vlbalist.py
+orcid-log.log
+output.txt
+README.html
+orcid-list.json

docs/examples/extracting_bibtex.py

@@ -0,0 +1,125 @@
+import codecs
+import logging
+import os
+
+import orcidpyclient as orcid
+
+logging.getLogger(__name__).setLevel(logging.INFO)
+
+# retrieve a profile from his ORCID
+me = orcid.get("0000-0001-5661-4587")
+
+TARGET_FODLER = "generated"
+
+
+def print_keyword(obj):
+    """Printing author keywords"""
+
+    print("[i] printing author keywords")
+    for key_word in obj.keywords:
+        print(key_word)
+
+
+def print_publications(obj):
+    """Printing author publications"""
+
+    print("[i] printing author publications")
+    for value in obj.publications:
+        print(value)
+
+
+def save_bibtex(bibtex, file_name="orcid-bibtex-output.bib", encoding="utf-8"):
+    """
+    (dict, str, str) -> None
+
+    Saves BibTeX into the file, grouping them by year.
+    """
+
+    file_name = "{0}/{1}".format(TARGET_FODLER, file_name)
+
+    _file = codecs.open(file_name, "w", encoding)
+
+    for key in bibtex:
+        _file.write("%%%%%%%%%%%%%%%% \n%% %s \n%%%%%%%%%%%%%%%%\n\n" % key)
+        bibtex_group = ""
+        for value in bibtex[key]:
+            bibtex_group += value + "\n\n"
+        _file.write(bibtex_group)
+
+    _file.close()
+
+    print("[i] bibtex was created, check following file: {0}".format(file_name))
+
+
+def save_nocite(bibtex, file_name="orcid-nocite-output.tex", encoding="utf-8"):
+    """
+    (dict, str, str) -> None
+
+    Saves BibTeX to the file with "nocite" command, grouped by year.
+    """
+
+    def extract_bibtex_id(s):
+        start = s.find("{") + 1
+        end = s.find(",", start)
+        return s[start:end]
+
+    file_name = "{0}/{1}".format(TARGET_FODLER, file_name)
+
+    _file = codecs.open(file_name, "w", encoding)
+
+    for key in bibtex:
+        _file.write("%%%%%%%%%%%%%%%% \n%% %s \n%%%%%%%%%%%%%%%%\n\n" % key)
+        nocite_group = ""
+        for value in bibtex[key]:
+            nocite_group += "\\nocite{" + extract_bibtex_id(value) + "}" + "\n"
+        _file.write(nocite_group)
+
+    _file.close()
+
+    print("[i] tex with \\nocite was created, check following file: {0}".format(file_name))
+
+
+def extract_bibtex(obj):
+    """
+    (Class) -> dict()
+
+    Takes an object with all publications from ORCID as the input and forms dict out of it.
+    """
+
+    bibtex = {}
+    for value in obj.publications:
+        if value.citation_type == "BIBTEX":
+            if value.publicationyear not in bibtex:
+                bibtex[value.publicationyear] = list()
+                bibtex[value.publicationyear].append(value.citation_value)
+            else:
+                bibtex[value.publicationyear].append(value.citation_value)
+        else:
+            print("[i] this publications is having no BIBTEX {0}".format(value))
+
+    return bibtex
+
+
+def orcid_bibtex(obj):
+    """
+    (Class) -> None
+
+    Extracts BibTeX from ORCID, saves it into the file
+    """
+
+    if not os.path.exists(TARGET_FODLER):
+        os.makedirs(TARGET_FODLER)
+
+    # extracting bibtex
+    orcid_bibtex = extract_bibtex(me)
+
+    # saving bibtex to file
+    save_bibtex(orcid_bibtex)
+
+    # citing extracted bibtex
+    save_nocite(orcid_bibtex)
+
+
+# print_keyword(me)
+# print_publications(me)
+orcid_bibtex(me)