Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] docs: Add developers section to docs #13745

Closed
wants to merge 10 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/root/dev/build/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@

Envoy build documentation
=========================

native building
---------------

using build container (amd64/arm64)
-----------------------------------

build operations
----------------

bazel survival guide
--------------------

dependency policies
-------------------
17 changes: 17 additions & 0 deletions docs/root/dev/community/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
Envoy developer community
=========================

contrib guidelines
------------------

repokitteh
----------

devstats
--------

slack channels
--------------

github
------
11 changes: 11 additions & 0 deletions docs/root/dev/core/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Envoy core documentation
========================

Core or extension?
------------------

API policies
------------

testing policies - unit/integration/coverage
--------------------------------------------
11 changes: 11 additions & 0 deletions docs/root/dev/docs/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
Writing docs
============

API documentation
-----------------

Configuration documentation
---------------------------

Creating a sandbox
------------------
17 changes: 17 additions & 0 deletions docs/root/dev/extensions/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
Envoy extensions documentation
==============================

types of extension
------------------

writing extensions
------------------

deploying extensions
--------------------

publishing extensions
---------------------

existing extensions
-------------------
13 changes: 13 additions & 0 deletions docs/root/dev/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
Developer documentation
-----------------------

.. toctree::
:maxdepth: 2

community/index
build/index
testing/index
core/index
extensions/index
docs/index
standards/index
21 changes: 21 additions & 0 deletions docs/root/dev/standards/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@

Code standards, linting, and style guides
=========================================

c++
---

python
------

starlark
--------

bazel
-----

bash
----

docs/rst
--------
16 changes: 16 additions & 0 deletions docs/root/dev/testing/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@

Envoy testing documentation
===========================


running tests
-------------

writing tests
-------------

coverage
--------

config_validation
-----------------
11 changes: 11 additions & 0 deletions docs/root/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ Envoy documentation
This is pre-release documentation. There is risk of it not being consistent with what is
currently implemented in Envoy, though we try to make things consistent as quickly as possible.

User documentation
------------------

.. toctree::
:maxdepth: 2

Expand All @@ -20,3 +23,11 @@ Envoy documentation
api/api
faq/overview
version_history/version_history

Developer documentation
-----------------------

.. toctree::
:maxdepth: 2

dev/index
Comment on lines +27 to +33
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I could go either way on this ultimately, but my suggestion from before was to make this hidden, and then just have a direct link to the dev docs root from our README. I think this would avoid polluting the end-user docs with dev docs while still allowing cross linking.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

at least with the redirects plugin in we have now this is not possible, and wouldnt be without quite a lot of hackery

i searched again today to see if there was anything like a "split-tree" rendering in sphinx and turned up nothing

i think to go the way you suggest is fighting the system too much, altho i guess its theoretically possible

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK it's not a big deal. Maybe just set max depth to 1 or something so not much shows up in the main index?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yep, sgtm