docs: Add initial structure for new docs

.gitignore

@@ -12,3 +12,5 @@ local.mk
 
 .envrc
 report.xml
+
+docs/_build/

MANIFEST.in

@@ -5,6 +5,7 @@ include LICENSE
 prune test
 prune flasher_stub
 prune .github
+prune docs
 exclude .git*
 exclude MANIFEST*
 

docs/README.md

@@ -0,0 +1,17 @@
+# Documentation Source Folder
+
+This folder contains source files of **esptool documentation**.
+
+The sources do not render well in GitHub and some information is not visible at all.
+
+Use actual documentation generated within about 20 minutes on each commit:
+
+# Hosted Documentation
+
+* English: https://docs.espressif.com/projects/esptool/
+
+The above URL is for the master branch latest version. Click the drop-down in the bottom left to choose a particular version or to download a PDF.
+
+# Building Documentation
+
+The documentation is built using the python package `esp-docs`, which can be installed by running `pip install esp-docs`. Running `build-docs --help` will give a summary of available options. For more information see the `esp-docs` documentation at https://github.com/espressif/esp-docs/blob/master/README.md

docs/_static/esptool_versions.js

@@ -0,0 +1,15 @@
+var DOCUMENTATION_VERSIONS = {
+    DEFAULTS: { has_targets: false,
+                supported_targets: [ "esp32" ]
+              },
+    VERSIONS: [
+      { name: "latest", has_targets: true, supported_targets: [ "esp8266", "esp32", "esp32s2", "esp32c3", "esp32s3" ] },
+    ],
+    IDF_TARGETS: [
+       { text: "ESP8266", value: "esp8266" },
+       { text: "ESP32", value: "esp32" },
+       { text: "ESP32-S2", value: "esp32s2" },
+       { text: "ESP32-S3", value: "esp32s3" },
+       { text: "ESP32-C3", value: "esp32c3" },
+    ]
+};

docs/conf_common.py

@@ -0,0 +1,18 @@
+from esp_docs.conf_docs import *  # noqa: F403,F401
+
+languages = ['en']
+idf_targets = ['esp8266', 'esp32', 'esp32s2', 'esp32s3', 'esp32c3']
+
+# link roles config
+github_repo = 'espressif/esptool'
+
+# context used by sphinx_idf_theme
+html_context['github_user'] = 'espressif'
+html_context['github_repo'] = 'esptool'
+
+html_static_path = ['../_static']
+
+# Extra options required by sphinx_idf_theme
+project_slug = 'esptool'
+
+versions_url = '_static/esptool_versions.js'

docs/en/about.rst

@@ -0,0 +1,6 @@
+About
+=====
+
+Esptool was started by Fredrik Ahlberg (@themadinventor) as an unofficial community project. Later, it was maintained by Angus Gratton (@projectgus). It is now supported by Espressif Systems.
+
+Esptool is Free Software under a GPLv2 license.

docs/en/conf.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+#
+# English Language RTD & Sphinx config file
+#
+# Uses ../conf_common.py for most non-language-specific settings.
+
+# Importing conf_common adds all the non-language-specific
+# parts to this conf module
+
+import datetime
+
+try:
+    from conf_common import *  # noqa: F403,F401
+except ImportError:
+    import os
+    import sys
+    sys.path.insert(0, os.path.abspath('../'))
+    from conf_common import *  # noqa: F403,F401
+
+# General information about the project.
+project = u'esptool'
+copyright = u'2016 - {}, Espressif Systems (Shanghai) Co., Ltd'.format(datetime.datetime.now().year)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+language = 'en'

docs/en/contributing.rst

@@ -0,0 +1,118 @@
+Contributions Guide
+===================
+
+We welcome contributions to the esptool project!
+
+How to Contribute
+-----------------
+
+Contributions to esptool - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_.
+
+Development Setup
+-----------------
+
+To also install additional tools needed for actually developing and
+testing esptool, run this command to install a development copy of
+esptool *plus* packages useful for development:
+
+::
+
+   pip install --user -e .[dev]
+
+(This command uses the “extras” feature of setuptools.)
+
+Reporting Issues
+----------------
+
+Please report bugs in esptool if you find them. However, before reporting a bug please check through the following:
+
+*  `Troubleshooting Section`_ - common problems and known issues
+
+*  `Existing Open Issues`_ - someone might have already encountered
+   this.
+
+If you don’t find anything, please `open a new issue`_.
+
+Sending Feature Requests
+------------------------
+
+Feel free to post feature requests. It’s helpful if you can explain
+exactly why the feature would be useful.
+
+There are usually some outstanding feature requests in the `existing
+issues list`_, feel free to add comments to them.
+
+Before Contributing
+-------------------
+
+Before sending us a Pull Request, please consider this list of points:
+
+* Have you tried running esptool test suite locally?
+
+* Is the code adequately commented for people to understand how it is structured?
+
+* Is there documentation or examples that go with code contributions?
+
+* Are comments and documentation written in clear English, with no spelling or grammar errors?
+
+* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
+
+* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback.
+
+Code Style & Static Analysis
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+esptool complies with Flake 8 and is valid Python 2 & Python 3 code
+(in the same source file.)
+
+When you submit a Pull Request, the GitHub Actions automated build
+system will run automated checks for this, using the `flake8 tool`_. To
+check your code locally before submitting, run ``python -m flake8`` (the
+flake8 tool is installed as part of the development requirements shown
+at the beginning of this document.)
+
+Automated Integration Tests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The test directory contains an integration suite with some integration
+tests for esptool.py:
+
+*  ``test_imagegen.py`` tests the elf2image command and is run
+   automatically by GitHub Actions for each Pull Request. You can run
+   this command locally to check for regressions in the elf2image
+   functionality.
+
+*  ``test_esptool.py`` is a `Python unittest`_ file that contains
+   integration tests to be run against real Espressif hardware.
+   These tests need real hardware so are not run automatically by GitHub
+   Actions, they need to be run locally in a command line with the following format:
+
+    ``./test_esptool.py <serial port> <name of chip> <baud rate> [optional test name(s)]``
+
+    For example, to run all tests on an ESP32 board connected to
+    /dev/ttyUSB0, at 230400bps:
+
+    ``./test_esptool.py /dev/ttyUSB0 esp32 230400``
+
+    Or to run the TestFlashing suite only on an ESP8266 board connected to
+    /dev/ttyUSB2\` at 460800bps:
+
+    ``./test_esptool.py /dev/ttyUSB2 esp8266 460800 TestFlashing``
+
+    (Note that some tests will fail at higher baud rates on some hardware.)
+
+Pull Request Process
+--------------------
+
+After you open the Pull Request, there will probably be some discussion in the comments field of the request itself.
+
+Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing.
+
+If this process passes, it will be merged onto the public github repository.
+
+.. _Troubleshooting Section: https://github.com/espressif/esptool/#troubleshooting
+.. _Existing Open Issues: https://github.com/espressif/esptool/issues
+.. _open a new issue: https://github.com/espressif/esptool/issues/new
+.. _existing issues list: https://github.com/espressif/esptool/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement
+.. _flake8 tool: http://flake8.readthedocs.io/en/latest/
+.. _Python unittest: https://docs.python.org/3/library/unittest.html