docs: add style guide instructions for writing Python docstrings

docs/markdown/Contributions/development/style-guide.md

@@ -406,3 +406,35 @@ class TestDemo(unittest.TestCase):
     def test_demo(self) -> None:
         self.assertEqual(y, 2)
 ```
+
+Documentation
+-------------
+
+User documentation uploaded to the [Pantsbuild web docs site](https://www.pantsbuild.org/docs) consists of two sections:
+* the reference docs that are generated from docstrings in the source code
+* the guides that are generated from the `docs/` directory's Markdown files.
+
+### Reference docs
+
+Not every docstring will make it to the website: currently only docstrings for global options, goals, subsystems, and targets are published. Please be extra vigilant when writing these and remember that docstrings are going to be rendered as Markdown. 
+
+It may be helpful to consider the following:
+
+* use the `softwrap` helper function to turn a multiline string into a softwrapped string
+* if you experience `mypy` typing issues using the `softwrap` for documenting subclasses of `Field` and `Target` classes, consider using the `help_text` convenience function
+* text inside the angle brackets (e.g. `<value>`) will be ignored when rendered if not wrapped in backticks
+* to create a numbered or bullet list, use 2 space indentation
+* to create a codeblock, use 4 space indentation (no need for triple backticks) and add one empty line between the code block and the text
+* make sure to use backticks to highlight config sections, command-line arguments, target names, and inline code examples.    
+
+It may be difficult to confirm the accuracy of text formatting in plain Python, so you may want to generate the relevant Markdown files to be able to preview them to confirm your docstrings are rendered as expected. The docstrings can be converted into Markdown files for visual inspection using a custom build script.
+
+You can run these commands to convert docstrings to Markdown files for the `main` and your local feature branch to identify the changed files and then preview only the relevant files to confirm the rendering makes sense.
+
+```text
+$ git checkout main
+$ pants run build-support/bin/generate_docs.py -- --no-prompt --output main-docs
+$ git checkout <your-branch>
+$ pants run build-support/bin/generate_docs.py -- --no-prompt --output branch-docs
+$ diff -qr main-docs branch-docs
+```