Repository: pyjanitor-devs/pyjanitor

Issue:
[BUG] Problem building docs on Window using "make html"
# Brief Description

Following the instructions on the [contributions](https://pyjanitor.readthedocs.io/contributing.html) page fails when trying to `make html` a symbolic link privilege not held error

# System Information

<!-- System information helps us. To keep things simple, just let us know the OS and Python version first.
You can provide the optional information later. -->

- Operating system: Windows  <!-- delete the appropriate ones -->
- OS details (optional):  10 Enterprise <!-- e.g. version, or Linux distro -->
- Python version (required): Python: 3.7.3 (default, Apr 24 2019, 15:29:51) [MSC v.1915 64 bit (AMD64)]

# Minimally Reproducible Code

<!-- If you provide minimal code that reproduces the problem, this makes it easier for us to debug what's going on.

Minimal code should be trivially copy/pastable into a Python interpreter in its entirety. Be sure to include imports.
-->
after activating the env and traversing to the ..\pyjanitor-dev\docs folder
`make html`

# Error Messages

<!-- If you get an error message, please paste it between the backticks here. -->

```
Traceback (most recent call last):
  File "C:\conda3x64\envs\pyjanitor-dev\lib\site-packages\sphinx\config.py", line 361, in eval_config_file
    execfile_(filename, namespace)
  File "C:\conda3x64\envs\pyjanitor-dev\lib\site-packages\sphinx\util\pycompat.py", line 86, in execfile_
    exec(code, _globals)
  File "c:\workspace\cjmayers\CODE\git_workspaces_external\pyjanitor\docs\conf.py", line 31, in <module>
    notebooks.symlink_to("../examples/notebooks")
  File "C:\conda3x64\envs\pyjanitor-dev\lib\pathlib.py", line 1330, in symlink_to
    self._accessor.symlink(target, self, target_is_directory)
OSError: symbolic link privilege not held
```



Discussion:
I have found that executing this command in an Administrator Powershell instance works and creates the not only ..\pyjanitor-dev\docs\_build directory with all the correct files but it also creates a shortcut to notebooks in the ..\docs directory.

Now if the `make html` is run through either normal instance or an Administrator instance of Powershell the following error occurs:

```
(pyjanitor-dev) c:\workspace\cjmayers\CODE\git_workspaces_external\pyjanitor\docs>make html
Running Sphinx v2.1.2

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "C:\conda3x64\envs\pyjanitor-dev\lib\site-packages\sphinx\config.py", line 361, in eval_config_file
    execfile_(filename, namespace)
  File "C:\conda3x64\envs\pyjanitor-dev\lib\site-packages\sphinx\util\pycompat.py", line 86, in execfile_
    exec(code, _globals)
  File "c:\workspace\cjmayers\CODE\git_workspaces_external\pyjanitor\docs\conf.py", line 29, in <module>
    if not notebooks.exists():
  File "C:\conda3x64\envs\pyjanitor-dev\lib\pathlib.py", line 1339, in exists
    self.stat()
  File "C:\conda3x64\envs\pyjanitor-dev\lib\pathlib.py", line 1161, in stat
    return self._accessor.stat(self)
OSError: [WinError 123] The filename, directory name, or volume label syntax is incorrect: 'notebooks'
```


If the notebook shortcut that was created in Administrator Powershell instance is removed (..\pyjanitor-dev\docs\notebooks) then we are go back to square one which requires an Admin to execute `make html`

After looking at the properties of the notebooks shortcut the properties for Target: and Start in: are blank making it a broken shortcut 

![01_shortcut_sm](https://user-images.githubusercontent.com/44857844/61188822-845d2b80-a64a-11e9-8d29-3b064f05e533.png)


A work around seems to be creating a junction where the synatx is `mklink /J "path to junction link" "path to target folder"`

The actual command needed for this bug is `mklink /J notebooks ..\examples\notebooks` which is executed from a normal shell in the ..\pyjanitor-dev\docs directory

Once this junction is created then `make html` works from a normal shell 

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -17,6 +17,7 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
+import platform
 import sys
 from pathlib import Path
 
@@ -26,10 +27,16 @@
 # Make a symlink in our sphinx source directory to the top-level
 # examples/notebooks directory so we can include notebooks in the doc
 notebooks = Path("./notebooks")
-if not notebooks.exists():
-    print("Making symlink to ../examples/notebooks")
-    notebooks.symlink_to("../examples/notebooks")
 
+if platform.system() == "Windows":
+    # Only for windows
+    os.system("mklink /J notebooks ..\\examples\\notebooks")
+else:
+    try:
+        print("Making symlink to ../examples/notebooks")
+        notebooks.symlink_to("../examples/notebooks")
+    except FileExistsError as e:
+        print(f"{notebooks} directory already exists. Not creating..")
 
 # -- Project information -----------------------------------------------------
 


Test patch: