How to contribute

the-examples-book repository is located on your local machine at /Users/myusername/projects/the-examples-book.

You’ve installed and configured GitHub Desktop, and your Current Repository (in the upper left-hand corner) is set to the-examples-book. Your screen should look similar to the following.

First, create a new branch from the "main" branch describing what you are doing, for example, "add-example-reading-data". To do this, click on the middle tab in GitHub Desktop which will show your current branch. Switch branches to the "main" branch. Once complete, click on the middle tab again, and click the New Branch button.

Figure 2. Click the New Branch button

You will be presented with a field and description. Ensure that you are creating a branch from the "main" branch. Enter the new branch name in the text area.

Figure 3. Name and create the new branch

Next, look at the current structure of the book and determine which module the example belongs in. In this case, this is a Python example, and therefore most likely belongs in the Python module.

Next, create a new file with the code of the example, and place this file in the examples directory in the python directory. We can see that there is already a python/examples/example01.py file, so let’s call our example example02.py.

If we have already determined we are just adding an example (vs. a page, or module), it is likely that there is already a page where this example fits appropriately. In this case, this is an example of ready a semi-colon separated file using pandas. Looking in the Python module, we can see that the pandas-read-write-data.adoc page is where this example belongs. Open the document in your favorite text editor, and add the following content in the Examples section of the page.

==== How do I read a csv file called `grades_semi.csv` into a `pandas` DataFrame, where `grades_semi.csv` is semi-colon-separated instead of comma-separated?

.Solution
====
[source, python]
----
import pandas as pd

myDF = pd.read_csv("./grades_semi.csv", sep=";")
myDF.head()
----

----
   grade       year
0    100     junior
1     99  sophomore
2     75  sophomore
3     74  sophomore
4     44     senior
----
====

Upon saving the document, you will see that GitHub Desktop shows the added content in our pandas-read-write-data.adoc page. This addition is staged.

Figure 4. Staged change in GitHub Desktop

The next step is commit the changes. Check the files you’d like to commit in the left-hand section of GitHub Desktop. In the lower left-hand section of GitHub Desktop, create a descriptive commit message, for example, "Add an example reading in semi-colon-separated data in Python". In the larger text area, you can add any other important details.

Figure 5. Changes ready to commit

Once the changes are committed, and you are ready to incorporate these changes to the book, the next step is to publish (or push) this branch to our remote repository (hosted on GitHub).

Figure 6. Branch ready to publish

Click Publish branch. You should see a screen indicating the branch is being published.

Figure 7. Publishing branch

Once published, your branch will be available to everyone using GitHub. In order to incorporate the changes in this branch to the "main" branch, we must create a pull request or merge request. Click the blue Create Pull Request button.

Figure 8. Click Create Pull Request

This will launch you browser and present you with the following screen. On this screen, you can (and should) assign a reviewer (the individual responsible for reviewing the content), designate an assignee (the individual who will actually merge the content), assign a label, and add any further comments.

Figure 9. Open pull request

the-examples-book repository is located on your local machine at /Users/myusername/projects/the-examples-book.

You’ve installed and configured GitHub Desktop, and your Current Repository (in the upper left-hand corner) is set to the-examples-book. Your screen should look similar to the following.

First, create a new branch from the "main" branch describing what you are doing, for example, "add-pd-dataframe-page". To do this, click on the middle tab in GitHub Desktop which will show your current branch. Switch branches to the "main" branch. Once complete, click on the middle tab again, and click the New Branch button.

Figure 11. Click the New Branch button

You will be presented with a field and description. Ensure that you are creating a branch from the "main" branch. Enter the new branch name in the text area.

Figure 12. Name and create the new branch

Next, look at the current structure of the book and determine which module the new page belongs in. In this case, this is a Python specific page, and therefore belongs in the Python module.

Next, create a new file in the Python module’s "pages" directory called pandas-dataframes.adoc. Add the following content to the new page.

= DataFrames

Some content.

== `some_function or method`

`some_function or method` description.

=== Examples

==== Question text

=== Resources

Make any other additions or changes you’d like to make to the contents of the new page, and save.

Open up the module’s nav.adoc file and add navigation to the new page. In this example, the following would be an appropriate before and after for nav.adoc.

* xref:introduction.adoc[Python]
** xref:pandas-intro.adoc[pandas]
*** xref:pandas-read-write-data.adoc[Reading & Writing Data]

* xref:introduction.adoc[Python]
** xref:pandas-intro.adoc[pandas]
*** xref:pandas-read-write-data.adoc[Reading & Writing Data]
*** xref:pandas-dataframes.adoc[DataFrames]

Upon saving the document, you will see that GitHub Desktop shows the added content in our pandas-read-write-data.adoc page. This addition is staged.

Figure 13. Staged change in GitHub Desktop

The next step is commit the changes. Check the files you’d like to commit in the left-hand section of GitHub Desktop. In the lower left-hand section of GitHub Desktop, create a descriptive commit message, for example, "Add a page that covers pandas DataFrame’s". In the larger text area, you can add any other important details.

Figure 14. Changes ready to commit

Once the changes are committed, and you are ready to incorporate these changes to the book, the next step is to publish (or push) this branch to our remote repository (hosted on GitHub).

Figure 15. Branch ready to publish

Click Publish branch. You should see a screen indicating the branch is being published.

Figure 16. Publishing branch

Once published, your branch will be available to everyone using GitHub. In order to incorporate the changes in this branch to the "main" branch, we must create a pull request or merge request. Click the blue Create Pull Request button.

Figure 17. Click Create Pull Request

This will launch you browser and present you with the following screen. On this screen, you can (and should) assign a reviewer (the individual responsible for reviewing the content), designate an assignee (the individual who will actually merge the content), assign a label, and add any further comments.

Figure 18. Open pull request

Create a new repository (public) with the following, minimal structure. Alternatively, you can copy the following files/directories from an existing appendix repository and copy into your new one: .github, .gitignore, content (directory), readme.md.

my_repo2
└── content
    ├── antora.yml
    └── modules
        └── ROOT
            ├── nav.adoc
            └── pages

4 directories, 2 files

Fill in the content of the antora.yml configuration file. The following is an example of a minimal antora.yml file.

name: example-appendix
title: Example Appendix
version: master
display_version: stable
start_page: ROOT:introduction.adoc
nav:
- modules/ROOT/nav.adoc

Create and place the desired AsciiDoc content in the pages directory. The introduction.adoc page will be the landing page for your appendix. For new high level pages, add lines to the nav.adoc file. If you do create further navigation in nav.adoc, you can then create new .adoc files with the corresponding name in the pages directory. Make sure to follow our page naming convention.

When you are satisfied with the results, modify the antora-playbook.yml file in our primary repository, and create a Pull Request. This is as simple as adding another item to our content  sources section of the .yml file. For example:

- url: https://github.com/my_organization/my_appendix_repo
  branches: main
  start_paths: content

* xref:example-appendix:ROOT:introduction.adoc[Example Appendix]

Open Automator.app, and select Folder Action, then click Choose.

Figure 19. Automator menu

At the top of the screen choose folder where your the-examples-book repository lives. Drag and drop Run Shell Script from the left-hand menu.

Figure 20. Folder action setup

Change Pass input to as arguments, and add the following script to the code block.

for f in "$@"
do
	if [[ $f == *.png ]]
	then
		/usr/local/bin/magick convert "$f" -filter Gaussian -sharpen 0x3 -resize 50% "$f"
		/usr/local/bin/pngquant 64 --skip-if-larger --strip --ext=.png --force "$f"
		/usr/local/bin/zopflipng -y "$f" "$f"
		/usr/local/bin/cwebp -q 30 "$f" -o "${f%.*}.webp"
		rm "$f"
	fi
done

Open finder and navigate to each "images" folders which you’d like automator to watch, and automatically convert and optimize .png files. This can be easily done by holding Ctrl+Click on the directory and attaching the workflow to each folder.