Merge pull request #3338 from cal-itp/ah_docs

Updated Parameterized Notebook Docs.

docs/publishing/sections/4_analytics_portfolio_site.md

@@ -15,7 +15,7 @@ You can find the Cal-ITP Analytics Portfolio at [analysis.calitp.org](https://an
 
 Before executing the build, there are a few prior steps you need to do.
 
-1. Set up netlify key:
+1. Set up netlify key/make sure your Netlify token is up to date:
 
    - Install netlify: `npm install -g netlify-cli`
    - Navigate to your main directory
@@ -30,7 +30,15 @@ Before executing the build, there are a few prior steps you need to do.
    - For the changes to take effect, open a new terminal or run `source ~/.bash_profile`
      - Back in your terminal, enter `env | grep NETLIFY` to see that your Netlify token is there
 
-2. Create a `.yml` file in [data-analyses/portfolio/sites](https://github.com/cal-itp/data-analyses/tree/main/portfolio/sites). Each `.yml` file is a site, so if you have separate research topics, they should each have their own `.yml` file.
+2. Create a `README.md` file in the repo where your work lies.
+
+   - Your file should always be titled as `README.md` and not other variants such as `README_gtfs.md` because the portfolio can only take a `README.md` file.
+   - If you do accidentally create a `README.md` file with extra strings, you can fix this by taking the following steps:
+     - `git rm portfolio/my_analysis/README_accidentally_named_something_else.md`
+     - `rm portfolio/my_analysis/_build/html/README_accidentally_named_something.html`. We use `rm` because \_build/html folder is not checked into GitHub
+     - `python portfolio/portfolio.py build my_report --no-execute-papermill --deploy` to rerun the portfolio to incorporate only the new changes to your `README.md` if the other pages are correct.
+
+3. Create a `.yml` file in [data-analyses/portfolio/sites](https://github.com/cal-itp/data-analyses/tree/main/portfolio/sites). Each `.yml` file is a site, so if you have separate research topics, they should each have their own `.yml` file.
 
    - This `.yml` file will include the directory to the notebook(s) you want to publish.
    - Name your `.yml` file. For now we will use `my_report.yml` as an example.
@@ -130,7 +138,7 @@ Before executing the build, there are a few prior steps you need to do.
 
    - By running `--deploy`, you are deploying the changes to display in the Analytics Portfolio.
    - **Note:** The `my_report` will be replaced by the name of your `.yml` file in [data-analyses/portfolio/sites](https://github.com/cal-itp/data-analyses/tree/main/portfolio/sites).
-   - If you have already deployed but want to make changes to the README, run: `python portfolio/portfolio.py build my_report --papermill-no-execute`
+   - If you have already deployed but want to make changes to the README, run: `python portfolio/portfolio.py build my_report --no-execute-papermill --deploy`
      - Running this is helpful for larger outputs or if you are updating the README.
 
 3. Once this runs, you can check the preview link at the bottom of the output. It should look something like:

docs/publishing/sections/5_notebooks_styling.md

@@ -1,16 +1,34 @@
 # Getting Notebooks Ready for the Portfolio
 
+- [See a sample parameterized notebook here.](https://github.com/cal-itp/data-analyses/blob/main/starter_kit/parameterized_notebook.ipynb)
+
+## Packages to include
+
+- Order matters, %%capture must go first.
+- `warnings.filterwarnings('ignore')` warnings from displaying in the portfolio site (`shared_utils`).
+
+```
+# Include this in the cell where packages are imported
+
+%%capture
+
+import warnings
+warnings.filterwarnings('ignore')
+
+import calitp_data_analysis.magics
+```
+
 ## Headers
 
 ### Parameterized Titles
 
-- If you're parameterizing the notebook, the first Markdown cell must include parameters to inject.
+- When parameterizing a notebook, the first Markdown cell must include parameters to inject.
   - Ex: If `district` is one of the parameters in your `sites/my_report.yml`, a header Markdown cell could be `# District {district} Analysis`.
   - Note: The site URL is constructed from the original notebook name and the parameter in the JupyterBook build: `0_notebook_name__district_x_analysis.html`
 
 ### Consecutive Headers
 
-- Headers must move consecutively in Markdown cells. No skipping!
+- Headers must move consecutively in Markdown cells or the parameterized notebook will not generate. No skipping!
 
 ```
 # Notebook Title
@@ -27,6 +45,12 @@
 
 ### Capturing Parameters
 
+- Create a code cell in which your parameter will be captured. Make sure the `parameter` tag for the cell is turned on.
+
+```
+ district_number = "4"
+```
+
 - If you're using a heading, you can either use HTML or capture the parameter and inject.
 
 - HTML - this option works when you run your notebook locally.
@@ -55,18 +79,6 @@
   ## District {district_number}
   ```
 
-### Suppress Warnings
-
-- Suppress warnings from displaying in the portfolio site (`shared_utils`).
-
-```
-# Include this in the cell where packages are imported
-
-%%capture
-import warnings
-warnings.filterwarnings('ignore')
-```
-
 ## Narrative
 
 - Narrative content can be done in Markdown cells or code cells.