Skip to content

How to contribute samples and guide chapters

Jump to bottom
Atma Mani edited this page Feb 21, 2022 · 10 revisions

First off, thank you for writing for the ArcGIS API for Python. Below are some guidelines to follow when writing your notebooks. These will help maintain the quality of content and help our CICD system integrate your articles and publish them on the https://developers.arcgis.com/python website (Python doc site) in a semi-automated process.

Section 1: Contribution guide

New branching model (New from Feb 2022)

The Python doc site will transition to a new theme in April 2022 with the 2.0.1 version release. This new theme comes with a new build system and branching model that aligns with the rest of the developer APIs from Esri. Use:

  • the next branch when you add new guides or samples. The next branch gets published only during planned releases and has a longer development cycle.
  • the default master branch for bug fixes and other minor edits. Any changes merged to the master will get auto-deployed to production within ~2 weeks.

Both these branches are "protected" and require the existing review and approval model.

Preview site (Esri employees only)

When authoring, you can preview your edits/pages either by running the site locally or on internal staging sites (after your PR has been merged). Setting up a local build of the site on your computer allows you to quickly preview your changes even before your commit them. This is handy when you are unsure how a UI element would show up on production. To learn how to set up this up follow the Readme on this AFD Python repo.

In addition to the local build, any changes merged to

Steps:

1. Clone this repo

Use your favorite GUI or CLI to clone this repo. Here is a handy help doc on how to do this. If you already have a clone, then update/sync both the master and next branches. Here is the help doc for GitHub GUI.

2. Create your branch

First, determine whether you are contributing new content or making a bug fix. For new content, create a branch off the next branch. For bug fixes, create a branch off master (the default branch). Name your branch using the format: <github_username>/<branch_name>.

Note: We are no longer using a forking model. Instead, create your branches directly off this repo.

3. Author, Commit, Push & Issue a PR

Author your notebook or edits to an existing notebook. If you have a local build of the developer site set up, preview your changes locally. Commit with a descriptive message. Ensure you are committing to your branch (and not master or next directly). Push up your changes to remote. Issue a PR (pull request) to the correct destination branch (next or master). Follow the checks on the PR template and update the description.

Once you make a PR, the reviewNB app will automatically post a message with a link to a notebook diff web app. The review process will start after this. Once your PR is approved, use the preview links to ensure the changes look good (available to Esri employees only).

Use section 2 below to understand how to construct/author your notebooks.

Section 2: Coding standards

Coding standards for your notebooks

Check out this article https://www.esri.com/about/newsroom/wp-content/uploads/2018/11/coding-standards-jupyter-ntbk.pdf for some guidelines on how to structure your notebooks and make them more reader-friendly.

Creating GIS connection

The preferred way to experience these notebooks is though ArcGIS Notebooks available in ArcGIS Online, Pro, Enterprise environments. To let your notebooks work in a broad range of such environments, create your GIS connections using home mode as shown here: gis = GIS('home').

When connecting to other servers, create GIS connections using profiles. We use the following reserved profile names

  • your_online_profile for arcgis_python account on ArcGIS Geosaurus Org
  • your_online_admin_profile for notebooks that require administrative creds to run against AGO (very few notebooks fall under this category)
  • your_enterprise_profile for arcgis_python account on PythonAPI Playground Enterprise
  • your_ent_admin_profile for an administrator account on PythonAPI Playground Enterprise

On your machines, you need to create these profiles. The idea here is to promote safer coding practices, by using home mode or login profiles and avoid patterns such as embedding passwords in notebooks. If connecting to an org that is different from above, use getpass to collect password through user input.

Publishing your GIS data

The Python API team maintains

To publish the layers required for your notebooks, use the api_data_owner on the Geosaurus Online org. If Online does not support your layer, then publish it on the Enterprise Org.

  • username: api_data_owner,
  • password: email the maintainers of this repo.

Once you publish the layers, delete protect them, and share them publicly. Share the original data (for features, zip up the shapefile or file geodatabase, for rasters, zip up the geoTIFF or imagery files) and upload it as an item inside the original_data folder.

Thus the data usage pattern is to first publish your content using api_data_owner manually and then access it in the notebooks using the account arcgis_python. Esri holds ownership of the data you publish.

Embedding maps in your notebook

See How to embed map images in your notebook wiki for details. Submit your PRs with the maps embedded

Using images in your notebook

Place all image files you want to reference in a notebook in this location: arcgis-python-api/static/img/. Then, in a notebook, reference the image relatively like ../../static/img/foo.png

Alternatively, base-64 encode your images and reference them like <img src="base64strhere">

Using links in your notebook

If you want to reference another guide page from an existing guide page, use the full https://developers.arcgis.com/python/foo/bar/ path in a notebook

Organizing the content

Below are some methods we employ to organize the content of guides and sample notebooks

  1. Avoid lengthy notebooks. Long notebooks are hard to read and browsers take a long time or sometimes fail to load. Hence, breakdown into two or more parts. Organize such that each part should talk about a concrete phase in your analysis.
  2. Use consistent voice. An active voice keeps the reader engaged. A passive voice gives a formal look. Whatever voice you use, keep it consistent. If in doubt, use active voice as most of this repo uses that.
  3. Provide sufficient context. You are the expert in your article, which is why you are writing it. However, the reader may not be. Hence provide context by explaining the current problem, give an overview of your solution before you jump off into code. Most users will jump to specific sections of guide chapters to look for example code. So, please keep that in mind when providing explanations. An easy way is, at each sub-section explain what you have done so far, and what you will be doing next.
  4. Explain why. Your notebook is likely doing a good job of explaining 'how to' do something. It is equally important to explain 'why' you are doing it. Readers remember 'why' more than 'how'. They can always look up the 'how' set of tasks.
  5. Use graphics liberally. If it helps, represent your workflow in a flow chart and embed it as a picture. Additionally, you can find relevant videos, images, story maps for your topic from credible sources and embed them. Ensure you are adequately citing references when the graphics are not yours.
  6. Use code formatting. When talking about aspects of the API - such as method names, class names, properties, etc., or while talking about a variable you defined earlier, use the markdown code formatting to refer to it.
  7. Always name your function arguments. Consider the following example
prj_folder_item = gis.content.create_folder("myOrthomappingProject", "john.doe")

vs

prj_folder_name = "myOrthomappingProject"
prj_folder_item = gis.content.create_folder(folder=prj_folder_name, owner=portal_username)

Both snippets do the same. However, the latter is more clear (even without using comments) to the reader as they get to know why you pass a string as the second argument. This becomes even more important when calling analysis functions that take multiple arguments.

  1. Visualize your GIS data frequently. When bringing in a new spatial dataset, plot it quickly on a map to show its extent and spatial characteristics. After each significant step, visualize the results you have achieved so far on a map. The same applies to non-spatial data that you may have in a DataFrame.
  2. Re-use the API objects. The Python API has a rich object notation to represent your GIS entities. When dealing with coordinates, instead of handling them as dictionaries or lists of lists, represent them as Point objects. Similarly, when dealing with a JSON or dictionary of features and their attributes, instead of manipulating them as dictionaries, construct a FeatureCollection or FeatureSet and use the built-in methods and properties. You get the idea, this applies to all other aspects as well.
  3. PEP 8. This one is obvious. Name your variables in a clear, PEP8 compliant fashion.

Submission checklist

  • Ensure your notebook file name is clear, descriptive, in lower cases, and without spaces. You are allowed to use underscore or hyphen (dash).
  • Ensure your notebook has a title, introduction, and a conclusion
  • Ensure you are using profiles to connect to GIS
  • The order of preference when choosing a GIS is, (1) Geosaurus AGO Org, (2) PythonAPI playground portal. Ensure you are not hitting any other Orgs or using any accounts other than the standard ones described above.
  • Spell check your notebook. You can copy text into MS Word or other spell check software.
  • Follow the coding guidelines article to structure your content
  • Embed your map images
  • Ensure your notebook runs in a reliable fashion
Clone this wiki locally