Optimize webpage
2
conf.py
|
@ -122,7 +122,7 @@ html_theme_options = {
|
||||||
'sidebar_collapse': True,
|
'sidebar_collapse': True,
|
||||||
'fixed_sidebar': True,
|
'fixed_sidebar': True,
|
||||||
'show_powered_by': False,
|
'show_powered_by': False,
|
||||||
'canonical_url': html_baseurl + '/',
|
'font_size': '1.05em',
|
||||||
}
|
}
|
||||||
|
|
||||||
html_logo = 'images/logo-text.svg'
|
html_logo = 'images/logo-text.svg'
|
||||||
|
|
|
@ -110,6 +110,10 @@ RST primer:
|
||||||
name: "Relay #42"
|
name: "Relay #42"
|
||||||
pin: GPIO13
|
pin: GPIO13
|
||||||
|
|
||||||
|
.. note::
|
||||||
|
|
||||||
|
Please note the empty line after the ``code-block`` directive. That is necessary.
|
||||||
|
|
||||||
- **Images**: To show images, use the ``figure`` directive:
|
- **Images**: To show images, use the ``figure`` directive:
|
||||||
|
|
||||||
.. code-block:: rst
|
.. code-block:: rst
|
||||||
|
@ -126,6 +130,13 @@ RST primer:
|
||||||
|
|
||||||
Optional figure caption.
|
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``
|
- **Notes and warnings**: You can create simple notes and warnings using the ``note`` and ``warning``
|
||||||
directives:
|
directives:
|
||||||
|
|
||||||
|
@ -182,6 +193,18 @@ RST primer:
|
||||||
1. Ordered Item #1
|
1. Ordered Item #1
|
||||||
2. Ordered Item #2
|
2. Ordered Item #2
|
||||||
|
|
||||||
|
- **imgtable**: ESPHome uses a custom RST directive to show the table on the front page (see `index.rst <https://github.com/esphome/esphome-docs/blob/current/index.rst>`__).
|
||||||
|
New pages need to be added to the ``imgtable`` list. The syntax is CSV with <PAGE NAME>, <FILE NAME> (without RST),
|
||||||
|
<IMAGE> (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
|
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 <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__.
|
please have a look at the `Sphinx reStructuredText Primer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__.
|
||||||
|
|
||||||
|
@ -195,53 +218,29 @@ Build
|
||||||
|
|
||||||
.. code-block:: bash
|
.. 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)
|
On Windows (PowerShell)
|
||||||
|
|
||||||
.. code-block:: 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 ``<CONTAINER_IP>:8000`` in your browser.
|
And then go to ``<CONTAINER_IP>:8000`` in your browser.
|
||||||
|
|
||||||
This way, you don't have to install the dependencies to build the documentation.
|
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
|
To check your documentation changes locally, you first need install sphinx (**with Python 3**).
|
||||||
`doxygen <http://www.doxygen.nl/>`__.
|
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
# in ESPHome-Docs repo:
|
# in ESPHome-Docs repo:
|
||||||
pip3 install -r requirements.txt
|
pip3 install -r requirements.txt
|
||||||
|
|
||||||
Next, you will also need to clone the `ESPHome-Core repository <https://github.com/esphome/ESPHome-Core>`__ 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:
|
Then, use the provided Makefile to build the changes and start a simple web server:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
# Update doxygen API docs
|
|
||||||
make doxyg
|
|
||||||
# Start web server on port 8000
|
# Start web server on port 8000
|
||||||
make webserver
|
make webserver
|
||||||
|
|
||||||
|
|
Before Width: | Height: | Size: 48 KiB After Width: | Height: | Size: 15 KiB |
Before Width: | Height: | Size: 69 KiB After Width: | Height: | Size: 20 KiB |
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 29 KiB After Width: | Height: | Size: 10 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 9.9 KiB |
Before Width: | Height: | Size: 166 KiB After Width: | Height: | Size: 14 KiB |
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 14 KiB |
Before Width: | Height: | Size: 8.0 KiB After Width: | Height: | Size: 17 KiB |
Before Width: | Height: | Size: 8.2 KiB After Width: | Height: | Size: 3.5 KiB |
BIN
images/dht.jpg
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 9.0 KiB |
BIN
images/dht12.jpg
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 6.9 KiB |
BIN
images/h801.jpg
Before Width: | Height: | Size: 48 KiB After Width: | Height: | Size: 9.7 KiB |
Before Width: | Height: | Size: 68 KiB After Width: | Height: | Size: 29 KiB |
Before Width: | Height: | Size: 24 KiB After Width: | Height: | Size: 9.7 KiB |
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 12 KiB |
BIN
images/hx711.jpg
Before Width: | Height: | Size: 49 KiB After Width: | Height: | Size: 19 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 49 KiB After Width: | Height: | Size: 15 KiB |
BIN
images/lcd.jpg
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 10 KiB |
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 39 KiB After Width: | Height: | Size: 11 KiB |
Before Width: | Height: | Size: 14 KiB After Width: | Height: | Size: 5.8 KiB |
BIN
images/mhz19.jpg
Before Width: | Height: | Size: 48 KiB After Width: | Height: | Size: 11 KiB |
Before Width: | Height: | Size: 196 KiB After Width: | Height: | Size: 18 KiB |
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 6.3 KiB |
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 8.6 KiB |
Before Width: | Height: | Size: 117 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 136 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 16 KiB |
BIN
images/pir.jpg
Before Width: | Height: | Size: 121 KiB After Width: | Height: | Size: 10 KiB |
BIN
images/pn532.jpg
Before Width: | Height: | Size: 42 KiB After Width: | Height: | Size: 14 KiB |
Before Width: | Height: | Size: 27 KiB After Width: | Height: | Size: 11 KiB |
Before Width: | Height: | Size: 41 KiB After Width: | Height: | Size: 14 KiB |
BIN
images/relay.jpg
Before Width: | Height: | Size: 130 KiB After Width: | Height: | Size: 13 KiB |
Before Width: | Height: | Size: 85 KiB After Width: | Height: | Size: 7.5 KiB |
Before Width: | Height: | Size: 33 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 90 KiB After Width: | Height: | Size: 8.2 KiB |
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 7.1 KiB |
Before Width: | Height: | Size: 25 KiB After Width: | Height: | Size: 6.0 KiB |
Before Width: | Height: | Size: 57 KiB After Width: | Height: | Size: 3.7 KiB |
Before Width: | Height: | Size: 22 KiB After Width: | Height: | Size: 7.6 KiB |
Before Width: | Height: | Size: 34 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 30 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 13 KiB |
Before Width: | Height: | Size: 170 KiB After Width: | Height: | Size: 14 KiB |
Before Width: | Height: | Size: 26 KiB After Width: | Height: | Size: 7.8 KiB |
Before Width: | Height: | Size: 5.6 KiB After Width: | Height: | Size: 2.8 KiB |
Before Width: | Height: | Size: 16 KiB After Width: | Height: | Size: 6.8 KiB |
|
@ -50,8 +50,3 @@ def create_sitemap(app, exception):
|
||||||
xml_declaration=True,
|
xml_declaration=True,
|
||||||
encoding='utf-8',
|
encoding='utf-8',
|
||||||
method="xml")
|
method="xml")
|
||||||
filename2 = app.outdir + "/sitemap2.xml"
|
|
||||||
ET.ElementTree(root).write(filename2,
|
|
||||||
xml_declaration=True,
|
|
||||||
encoding='utf-8',
|
|
||||||
method="xml")
|
|
||||||
|
|