diff --git a/conf.py b/conf.py index 3142f8966..02c1a705f 100644 --- a/conf.py +++ b/conf.py @@ -122,7 +122,7 @@ html_theme_options = { 'sidebar_collapse': True, 'fixed_sidebar': True, 'show_powered_by': False, - 'canonical_url': html_baseurl + '/', + 'font_size': '1.05em', } html_logo = 'images/logo-text.svg' diff --git a/guides/contributing.rst b/guides/contributing.rst index 5b220104c..b7e568ccf 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -110,6 +110,10 @@ RST primer: name: "Relay #42" pin: GPIO13 + .. note:: + + Please note the empty line after the ``code-block`` directive. That is necessary. + - **Images**: To show images, use the ``figure`` directive: .. code-block:: rst @@ -126,6 +130,13 @@ RST primer: Optional figure caption. + .. note:: + + All images in the documentation need to be as small as possible to ensure + fast page load times. For normal figures the maximum size should be at most + about 1000x800px or so. Additionally, please use online tools like + https://tinypng.com/ or https://tinyjpg.com/ to further compress images. + - **Notes and warnings**: You can create simple notes and warnings using the ``note`` and ``warning`` directives: @@ -182,6 +193,18 @@ RST primer: 1. Ordered Item #1 2. Ordered Item #2 +- **imgtable**: ESPHome uses a custom RST directive to show the table on the front page (see `index.rst `__). + New pages need to be added to the ``imgtable`` list. The syntax is CSV with , (without RST), + (in top-level images/ directory). The aspect ratio of these images should be 8:10 (or 10:8) but exceptions are possible. + + Because these images are served on the main page, they need to be compressed heavily. SVGs are prefered over JPGs + and JPGs should be max. 300x300px. + If you have imagemagick installed, you can use this command to convert the thumbnail: + + .. code-block:: bash + + convert -sampling-factor 4:2:0 -strip -interlace Plane -quality 80% -resize 300x300 in.jpg out.jpg + reStructured text can do a lot more than this, so if you're looking for a more complete guide please have a look at the `Sphinx reStructuredText Primer `__. @@ -195,53 +218,29 @@ Build .. code-block:: bash - docker run --rm -v "$PWD/..":/data -p 8000:8000 -it ottowinter/esphomedocs + docker run --rm -v "$PWD/":/data -p 8000:8000 -it ottowinter/esphomedocs On Windows (PowerShell) .. code-block:: powershell - docker run --rm -v ${PWD}/..:/data -p 8000:8000 -it ottowinter/esphomedocs + docker run --rm -v ${PWD}/:/data -p 8000:8000 -it ottowinter/esphomedocs And then go to ``:8000`` in your browser. This way, you don't have to install the dependencies to build the documentation. -To check your documentation changes locally, you first need install sphinx (**with Python 3**) and -`doxygen `__. +To check your documentation changes locally, you first need install sphinx (**with Python 3**). .. code-block:: bash # in ESPHome-Docs repo: pip3 install -r requirements.txt -Next, you will also need to clone the `ESPHome-Core repository `__ into -the paret folder where ``ESPHome-Docs`` sits like this: - -.. code-block:: text - - ├── ESPHome-Docs/ - │   ├── api/ - │   ├── esphomeyaml/ - │   ├── Doxygen - │   ├── Makefile - │   ├── index.rst - │   └── ... - └── ESPHome-Core/ - ├── docker/ - ├── examples/ - ├── lib/ - ├── src/ - ├── library.json - ├── platformio.ini - └── ... - Then, use the provided Makefile to build the changes and start a simple web server: .. code-block:: bash - # Update doxygen API docs - make doxyg # Start web server on port 8000 make webserver diff --git a/images/ads1115.jpg b/images/ads1115.jpg index e15f8efc4..97fd85340 100644 Binary files a/images/ads1115.jpg and b/images/ads1115.jpg differ diff --git a/images/apds9960.jpg b/images/apds9960.jpg index e72f1a05d..28bd52054 100644 Binary files a/images/apds9960.jpg and b/images/apds9960.jpg differ diff --git a/images/bh1750.jpg b/images/bh1750.jpg index 681d2280e..2cac9b769 100644 Binary files a/images/bh1750.jpg and b/images/bh1750.jpg differ diff --git a/images/bme280.jpg b/images/bme280.jpg index b2b1cacba..1715ce557 100644 Binary files a/images/bme280.jpg and b/images/bme280.jpg differ diff --git a/images/bme680.jpg b/images/bme680.jpg index f5077d936..5c391d5f1 100644 Binary files a/images/bme680.jpg and b/images/bme680.jpg differ diff --git a/images/bmp180.jpg b/images/bmp180.jpg index d0d69a207..58a993058 100644 Binary files a/images/bmp180.jpg and b/images/bmp180.jpg differ diff --git a/images/bmp280.jpg b/images/bmp280.jpg index 29ed6aeaa..c5410c423 100644 Binary files a/images/bmp280.jpg and b/images/bmp280.jpg differ diff --git a/images/cookbook-sonoff-fishpond-pump.jpg b/images/cookbook-sonoff-fishpond-pump.jpg index fdbb27338..c17b77bd2 100644 Binary files a/images/cookbook-sonoff-fishpond-pump.jpg and b/images/cookbook-sonoff-fishpond-pump.jpg differ diff --git a/images/dallas.jpg b/images/dallas.jpg index 1a2afd19e..12b2e8393 100644 Binary files a/images/dallas.jpg and b/images/dallas.jpg differ diff --git a/images/dht.jpg b/images/dht.jpg index 44906490e..800813299 100644 Binary files a/images/dht.jpg and b/images/dht.jpg differ diff --git a/images/dht12.jpg b/images/dht12.jpg index b2202598b..05e6eca85 100644 Binary files a/images/dht12.jpg and b/images/dht12.jpg differ diff --git a/images/h801.jpg b/images/h801.jpg index 98887d15c..df3603bf1 100644 Binary files a/images/h801.jpg and b/images/h801.jpg differ diff --git a/images/hdc1080.jpg b/images/hdc1080.jpg index a793da228..40aca2575 100644 Binary files a/images/hdc1080.jpg and b/images/hdc1080.jpg differ diff --git a/images/hmc5883l.jpg b/images/hmc5883l.jpg index 643914984..311905a1a 100644 Binary files a/images/hmc5883l.jpg and b/images/hmc5883l.jpg differ diff --git a/images/htu21d.jpg b/images/htu21d.jpg index 0c2ead618..4db1d033b 100644 Binary files a/images/htu21d.jpg and b/images/htu21d.jpg differ diff --git a/images/hx711.jpg b/images/hx711.jpg index 7d2238366..0c1584186 100644 Binary files a/images/hx711.jpg and b/images/hx711.jpg differ diff --git a/images/ina219.jpg b/images/ina219.jpg index 25030d990..83eb00f00 100644 Binary files a/images/ina219.jpg and b/images/ina219.jpg differ diff --git a/images/ina3221.jpg b/images/ina3221.jpg index 3c7a9ba52..fbbcece0d 100644 Binary files a/images/ina3221.jpg and b/images/ina3221.jpg differ diff --git a/images/lcd.jpg b/images/lcd.jpg index 3d165218b..a346933cf 100644 Binary files a/images/lcd.jpg and b/images/lcd.jpg differ diff --git a/images/max31855.jpg b/images/max31855.jpg index cce0781a7..195f2f19b 100644 Binary files a/images/max31855.jpg and b/images/max31855.jpg differ diff --git a/images/max6675.jpg b/images/max6675.jpg index a2b2c62a5..3ac2156d2 100644 Binary files a/images/max6675.jpg and b/images/max6675.jpg differ diff --git a/images/max7219.jpg b/images/max7219.jpg index 230c226f2..6c86c9690 100644 Binary files a/images/max7219.jpg and b/images/max7219.jpg differ diff --git a/images/mhz19.jpg b/images/mhz19.jpg index 2f71f7aed..399e20277 100644 Binary files a/images/mhz19.jpg and b/images/mhz19.jpg differ diff --git a/images/mpu6050.jpg b/images/mpu6050.jpg index 36018a260..ceb1c8ec1 100644 Binary files a/images/mpu6050.jpg and b/images/mpu6050.jpg differ diff --git a/images/ms5611.jpg b/images/ms5611.jpg index 3f7d42715..61a68e1ec 100644 Binary files a/images/ms5611.jpg and b/images/ms5611.jpg differ diff --git a/images/nextion.jpg b/images/nextion.jpg index 500eb0ac3..66f56d33a 100644 Binary files a/images/nextion.jpg and b/images/nextion.jpg differ diff --git a/images/nodemcu_esp32.jpg b/images/nodemcu_esp32.jpg index b1aef9579..f6122d7d7 100644 Binary files a/images/nodemcu_esp32.jpg and b/images/nodemcu_esp32.jpg differ diff --git a/images/nodemcu_esp8266.jpg b/images/nodemcu_esp8266.jpg index 81c49fd74..29808b63f 100644 Binary files a/images/nodemcu_esp8266.jpg and b/images/nodemcu_esp8266.jpg differ diff --git a/images/pca9685.jpg b/images/pca9685.jpg index 7266c5f29..fffc25e40 100644 Binary files a/images/pca9685.jpg and b/images/pca9685.jpg differ diff --git a/images/pcf8574.jpg b/images/pcf8574.jpg index 2d1694706..a5b0e73c3 100644 Binary files a/images/pcf8574.jpg and b/images/pcf8574.jpg differ diff --git a/images/pir.jpg b/images/pir.jpg index 0f71fc3d9..d1b14f986 100644 Binary files a/images/pir.jpg and b/images/pir.jpg differ diff --git a/images/pn532.jpg b/images/pn532.jpg index d5d6193f5..c44b9fed5 100644 Binary files a/images/pn532.jpg and b/images/pn532.jpg differ diff --git a/images/power_meter.jpg b/images/power_meter.jpg index 43af26f85..7fb03022d 100644 Binary files a/images/power_meter.jpg and b/images/power_meter.jpg differ diff --git a/images/rdm6300.jpg b/images/rdm6300.jpg index b2e4f243c..ca35a4491 100644 Binary files a/images/rdm6300.jpg and b/images/rdm6300.jpg differ diff --git a/images/relay.jpg b/images/relay.jpg index e3ee6c0a5..f34e2b595 100644 Binary files a/images/relay.jpg and b/images/relay.jpg differ diff --git a/images/rotary_encoder.jpg b/images/rotary_encoder.jpg index 1408376f0..b49ea868e 100644 Binary files a/images/rotary_encoder.jpg and b/images/rotary_encoder.jpg differ diff --git a/images/sht3xd.jpg b/images/sht3xd.jpg index 49db40b7e..ff49a22d2 100644 Binary files a/images/sht3xd.jpg and b/images/sht3xd.jpg differ diff --git a/images/sonoff_4ch.jpg b/images/sonoff_4ch.jpg index a00a81cec..b88d86570 100644 Binary files a/images/sonoff_4ch.jpg and b/images/sonoff_4ch.jpg differ diff --git a/images/sonoff_basic.jpg b/images/sonoff_basic.jpg index d582789c6..7dd3502d1 100644 Binary files a/images/sonoff_basic.jpg and b/images/sonoff_basic.jpg differ diff --git a/images/sonoff_dual_r2.jpg b/images/sonoff_dual_r2.jpg index 8e0d1c8cd..68a842d78 100644 Binary files a/images/sonoff_dual_r2.jpg and b/images/sonoff_dual_r2.jpg differ diff --git a/images/sonoff_s20.jpg b/images/sonoff_s20.jpg index b6d207e50..cbe238801 100644 Binary files a/images/sonoff_s20.jpg and b/images/sonoff_s20.jpg differ diff --git a/images/ssd1306.jpg b/images/ssd1306.jpg index 6d90cad10..5ac7e25b6 100644 Binary files a/images/ssd1306.jpg and b/images/ssd1306.jpg differ diff --git a/images/tcs34725.jpg b/images/tcs34725.jpg index c25ad2570..8728731cc 100644 Binary files a/images/tcs34725.jpg and b/images/tcs34725.jpg differ diff --git a/images/temt6000.jpg b/images/temt6000.jpg index 14bd38fdd..bc0520545 100644 Binary files a/images/temt6000.jpg and b/images/temt6000.jpg differ diff --git a/images/tsl2561.jpg b/images/tsl2561.jpg index 794a4efd3..2db89d119 100644 Binary files a/images/tsl2561.jpg and b/images/tsl2561.jpg differ diff --git a/images/ultrasonic.jpg b/images/ultrasonic.jpg index 41a6e609d..6ec49f110 100644 Binary files a/images/ultrasonic.jpg and b/images/ultrasonic.jpg differ diff --git a/images/waveshare_epaper.jpg b/images/waveshare_epaper.jpg index 37045f0ed..518e7d978 100644 Binary files a/images/waveshare_epaper.jpg and b/images/waveshare_epaper.jpg differ diff --git a/images/xiaomi_miflora.jpg b/images/xiaomi_miflora.jpg index ef3475c2b..906cf8b40 100644 Binary files a/images/xiaomi_miflora.jpg and b/images/xiaomi_miflora.jpg differ diff --git a/images/xiaomi_mijia.jpg b/images/xiaomi_mijia.jpg index f5e4d9540..c67fb78c3 100644 Binary files a/images/xiaomi_mijia.jpg and b/images/xiaomi_mijia.jpg differ diff --git a/sitemap.py b/sitemap.py index 98ab295e0..e84c553e5 100644 --- a/sitemap.py +++ b/sitemap.py @@ -50,8 +50,3 @@ def create_sitemap(app, exception): xml_declaration=True, encoding='utf-8', method="xml") - filename2 = app.outdir + "/sitemap2.xml" - ET.ElementTree(root).write(filename2, - xml_declaration=True, - encoding='utf-8', - method="xml")