Added troubleshooting

Author: rcwoshimao

README.md

@@ -50,4 +50,95 @@ To explain up-front:
 - When taking an exam for practice, we recommend having a copy of the DSC 10 reference sheet open in another tab, as well as a second copy of the exam, so you can access the data descriptions.
 
 
+### Troubleshooting tips 
+#### yaml `ModuleNotFoundError` 
+```
+python run.py
+Traceback (most recent call last):
+  File "..../practice.dsc40a.com/run.py", line 1, in <module>
+    import yaml
+ModuleNotFoundError: No module named 'yaml'
+```
+**Example Behavior:**
+```
+(base) practice.dsc40a.com % python run.py
+Traceback (most recent call last):
+  File "practice.dsc40a.com/run.py", line 1, in <module>
+    import yaml
+ModuleNotFoundError: No module named 'yaml'
+(base) practice.dsc40a.com % pip3 install PyYAML
+
+[notice] A new release of pip is available: 24.2 -> 25.3
+[notice] To update, run: python3.12 -m pip install --upgrade pip
+error: externally-managed-environment
+
+× This environment is externally managed
+╰─> To install Python packages system-wide, try brew install
+    xyz, where xyz is the package you are trying to
+    install.
+    
+    If you wish to install a Python library that isn't in Homebrew,
+    use a virtual environment:
+    
+    python3 -m venv path/to/venv
+    source path/to/venv/bin/activate
+    python3 -m pip install xyz
+    
+    If you wish to install a Python application that isn't in Homebrew,
+    it may be easiest to use 'pipx install xyz', which will manage a
+    virtual environment for you. You can install pipx with
+    
+    brew install pipx
+    
+    You may restore the old behavior of pip by passing
+    the '--break-system-packages' flag to pip, or by adding
+    'break-system-packages = true' to your pip.conf file. The latter
+    will permanently disable this error.
+    
+    If you disable this error, we STRONGLY recommend that you additionally
+    pass the '--user' flag to pip, or set 'user = true' in your pip.conf
+    file. Failure to do this can result in a broken Homebrew installation.
+    
+    Read more about this behavior here: <https://peps.python.org/pep-0668/>
+
+note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
+hint: See PEP 668 for the detailed specification.
+```
+**Solution:** 
+- If you have already installed the above packages but still encounter this issue, 
+- Taken DSC 80,
+Use DSC 80 environment either in terminal or in VS code. 
+
+#### Pathname issue 
+```
+File "practice.dsc40a.com/run.py", line 549, in <module>
+    write_all_pages()
+  File "practice.dsc40a.com/run.py", line 508, in write_all_pages
+    write_page(path, called_from_write_all_pages=True)
+  File "practice.dsc40a.com/run.py", line 421, in write_page
+    page, title = process_page(path, is_discussion=is_discussion)
+                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "practice.dsc40a.com/run.py", line 389, in process_page
+    out += stitch(params['problems'], params['show_solution'])
+           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+  File "practice.dsc40a.com/run.py", line 121, in stitch
+    r = open(path, 'r', encoding='UTF-8').read()
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+FileNotFoundError: [Errno 2] No such file or directory: 'problems/ss2-24-final\\ss2-24-final-q01.md'
+```
+**Cause**: Windows and mac have different ways of doing pathnames. 
+**Solution**: In run.py, you can see the following line:
+
+```python
+def stitch(files, show_solution, toc=False):
+    ...
+    for i, path in enumerate(paths):
+            
+            # Comment the line below out if you are using windows.
+            path = path.replace('\\', '/')
+            # Coment the line above out if you are using windows. 
 
+            path = os.path.normpath(path)
+    ...
+```
+Follow the instruction of the comments. If you have issue with pathname, the cause is likely somewhere in this function. 

run.py

@@ -108,7 +108,11 @@ def stitch(files, show_solution, toc=False):
         pass
 
     for i, path in enumerate(paths):
+        
+        # Comment the line below out if you are using windows.
         path = path.replace('\\', '/')
+        # Coment the line above out if you are using windows. 
+
         path = os.path.normpath(path)
         # This case only happens for discussion worksheets, when we provide a question along with a "data info" sheet just for that question
         if ', ' in path: