How to contribute samples and guide chapters - EsriJapan/arcgis-python-api GitHub Wiki

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 in a semi-automated process.

Create a branch for your edits

Earlier, we recommended contributors fork the repo, make changes and issue a PR. However this process makes collaborative editing of a PR tedious. Hence we recommend creating a branch under then main repo for your PRs. Name your branch as <github_username>/<branch_name> for easier tracking.

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 administrator account on PythonAPI Playground Enterprise

On your machines, you need to create these profiles. We are in the process of making these profiles available on notebooks.esri.com site, so yours can run these notebooks readily. The overall idea is, our users will create corresponding profiles and run these against their own deployments.

Accessing the GIS data

The Python API team maintains an ArcGIS Enterprise running at https://pythonapi.playground.esri.com/portal/home/. You can access this Enterprise GIS from your notebooks using the credentials username: arcgis_python and password: amazing_arcgis_123. Any outputs, maps, layers, etc. created by this account would be periodically erased.

To publish the layers required for your notebooks, use a different account: username: api_data_owner, password: email the maintainers of this repo. Once you publish the layers, delete protect it and share it for all in the organization. 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 coordiantes, 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) PythonAPI playground portal (2) Geosaurus AGO Org. Ensure you are not hitting any other Orgs or using any accounts other than the standard ones described above.
  • Ensure your notebook file name has all lower characters, spaces replaced with dashes, no apostrophe or special characters
  • Spell check your notebook
  • Follow the coding guidelines article to structure your content
  • Embed your map images
  • Ensure your notebook runs in a reliable fashion