zilliqa/dev-portal

Documentation for Zilliqa developer

Zilliqa developer documentation

This repository contains the Zilliqa developer documentation.

• The main branch has CD at [https://developer-portal.zilstg.dev/]
• Releases to go to [https://developer-portal.zilliqa.com]

How it works

The developer portal is a pair of mkdocs materials-themed sites - one for Zilliqa 1 and one for Zilliqa 2.

The Zilliqa 1 site is static. The Zilliqa 2 site includes content created by the rust program in docgen - see below.

They are served in production by an nginx container containing the routing between the two, built by the Dockerfile and using the config file from default.conf.

The material theme is fairly heavily customised with overrides in both Zilliqa 1 and Zilliqa 2.

Docgen

The docgen program:

• Reads the zq2_spec.yaml file in this directory.
• Clones Zilliqa 2 into cache/zq2
• Runs the docgen program in Zilliqa 2 to generate API documentation.
• Repeats the process for all the versions of Zilliqa 2 it is to document.
• Generates an mkdocs.yaml

mkdocs.yaml for zq2 is generated from:

• zq2/mkdocs.in.yaml, which inherits from
• zq2/parenty.yaml

Developing

Development is controlled by the Makefile in this directory.

You will need mkdocs. Make sure you're in a venv (because mkdocs doesn't seem to like installing outside one):

python -m venv ~/mydir
source ~/mydir/bin/activate

And then:

pip3 install -r requirements.txt

You will also need enough local tooling installed to build ZQ2; this starts with installing Rust, but there are other tools - including cmake and protobuf required. Check the zq2 repository for details.

Now,

• make dev1 will make and serve the ZQ1 docs locally on port 8000.
• make dev2 will do the same with the ZQ2 docs.

You can set SERVEROPTS to pass option (usually -a <listen_address>:<port>) to mkdocs serve.

If you want to check containerised builds, make run-image will do that for you and run it on port 8080.

dev-portal's Issues

Add Zilliqa 2 documentation

Add zq2 autogenerated documentation to the documentation portal.

Fix developer portal link, add multisig scilla repo reference, fix embedded faucet, fix network list.

.. from #22

Add README.md and move api_url into config file.

• We should have a README.md that describes setup
• API URLs should be in the config file and not hardwired in docgen where you can't easily change them per version of the docs generated.

Add zq2 node joining documentation

Remove link to zilliqa 2 docs from title page

... at marketing's request ...

Implement a version index page in docgen

It would be nice to have a versions index page (https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages) that you could link to.

Allow us to generate docs from an external zq2 repo

.. this makes things easier to test without lots of error-prone rsync

requirements won't install on Ubuntu 14.04

.. because 14.04 has python 3.12 and PyYAML 6.0 doesn't support python 3.12 ..

Generate "overridden" zq2 docs into an appropriately named documentation version

... so we don't hijack the list of versions that actually need documenting.

Update deployment plan

zq2/docs/changes.md contains a description of how we will transition from Zilliqa 1 to Zilliqa 2; this needs updating to whatever the current plan is - probably by @DrZoltanFazekas

Document deterministic deployment proxy

See https://github.com/Zilliqa/zq2/pull/1072/files