Hi, and thanks!

This is not a bad idea, although I'm concerned that by adding a heading layer to the document, we lose the nested headings in the table of contents on https://docs.cilium.io/en/latest/security/policy/: compare your version

... with the current one:

I think it's nice to have this information quickly available from the ToC.

Let's see, maybe we can find another way to adjust this? We could change the current headings to “Network Policy - Layer 3 Examples” (and similarly for the other sections)? Or we could split this document into several smaller ones, such that “Layer 3 Examples” becomes a correct heading for the document, and no longer a section among others? @joestringer do you have an opinion?

True, this pushes the other headlines a level down. The thing is that if a page has no single highest-level headline, then the first headline is still taken as the page title, which is also an issue for search engines. I think splitting up into multiple pages makes more sense then.

This might affect other sections/pages, too; I haven't checked that, just ran into this here when searching for L4 docs. 😅

On another note, I also found it confusing to only see "examples", although I was looking for the full language specification; maybe that should rather be the respective page's title if split up.

@orangecms thanks for digging into this! Indeed I think we can improve the docs to split more clearly into different document types. @pmatulis put quite a bit of thought a while back into how we would ideally structure many aspects of the docs, so I think this would be a good blueprint to figure out how to improve different areas of the docs. The trick as always is how to pick something small to start and make some early progress so we don't get bogged down in big changes :)

Here's the Cilium Feature Proposal (really a design proposal) for a doc improvement plan:
https://github.com/cilium/design-cfps/blob/main/cilium/CFP-39757-doc-improvement-plan.md

@orangecms thanks for digging into this! Indeed I think we can improve the docs to split more clearly into different document types. @pmatulis put quite a bit of thought a while back into how we would ideally structure many aspects of the docs, so I think this would be a good blueprint to figure out how to improve different areas of the docs. The trick as always is how to pick something small to start and make some early progress so we don't get bogged down in big changes :)

Here's the Cilium Feature Proposal (really a design proposal) for a doc improvement plan: https://github.com/cilium/design-cfps/blob/main/cilium/CFP-39757-doc-improvement-plan.md

Uh-oh, heading on from seemingly low-hanging fruit to reading CFPs... 😅
I'll check it out when I find some time, thank you! 🥰

Hehe, no pressure by any means - I read the comment:

On another note, I also found it confusing to only see "examples", although I was looking for the full language specification; maybe that should rather be the respective page's title if split up.

.. and I thought "Ah yes, we aren't clearly defining the page as either reference or tutorial but rather mixing a bit of both." This specifically relates to the following section: https://github.com/cilium/design-cfps/blob/main/cilium/CFP-39757-doc-improvement-plan.md#appendix-c---documentation-types

That said if you had other small ideas on how to improve the docs, feel free to submit them whether you get the chance to read into the CFP above or not. We haven't got to a point where we're enforcing contributions to follow the above, so it's more like a blueprint or "north star" to help inform reviewers how we might steer docs contributions, but it's not "required reading" per se 😅

Alright, I've split up the page, that appears to be the best move for now.

The PR title cannot be changed by the author anymore, unfortunately, otherwise I'd adjust it (thanks GitHub...).

Alright, adjusted - thank you! :)

I'm getting this here, no idea what the error/warning is; I'll see if I can get some "verbose" output or smth.

writing output...
building [html]: targets for 653 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources...
looking for now-outdated files... none found
preparing documents... done
copying downloadable files... [100%] security/audits/CiliumFuzzingAudit2022.pdf
copying static files... done
copying extra files... done
done
writing output... [100%] security/policy/index .. security/tls-visibility
generating indices... genindex http-routingtable done
writing additional pages... search done
copying images... [100%] security/images/cilium-tls-interception.png
dumping search index in English (code: en)... done
dumping object inventory... done
Writing redirects...
build finished with problems, 1 warning.
make: *** [Makefile:143: html] Error 1

nvm, a make clean did the magic, all good!

/test

Changes are now live on /latest: https://docs.cilium.io/en/latest/security/policy/ .

@cilium/docs-structure any strong opinions about whether to backport this or keep it only for /latest until /v1.20 later this year?

No strong opinion.

• It doesn't really add any new information, so maybe not worth the hassle.
• On the other hand, if any other changes in the network policies docs need to be backported, we'll have conflicts, so why not.

Let's mark for backport to 1.19 (we could even try older branches?) and see if automated backports work without conflict?

Conflicts with 1.19 are probably less likely given we only branched roughly a month ago. Older releases are more likely to differ, given this is removing the language.rst file.