[ENH] Discussion of Syntax Choices

[mmcky]

@najuzilu @AakashGfude

I have noticed the syntax for algorithms (and a couple of other directives) are children of the proof directive entry point. I guess this is in effect showing that directives are all part of the proof extension.

Do you think this is the right syntax choice here?

Just wondering if we should also support more generic entry points (as well) such as algorithm:

```{algorithm} Title
<options>

Text
```

Introduce top-level directive names:

Pro:

1. Easier to remember for authors if extension is included by default with jupyter-book for out of the box support

Con:

1. A benefit of proof:algorithm is for compatibility with sphinxcontrib-proof
2. possible namespace collisions with other packages with more generic names.

[AakashGfude]

@mmcky is there any popular package out there which has these generic syntaxes which the authors might use? If not, then probably we can get away with it?

[jstac]

I'm happy with this as is --- as you say, it's compatible with sphinxcontrib-proof.

At some point we can reach out to those guys and see if there is the possibility of unification.

[najuzilu]

Personally I have no preference. It would be incredibly easy to support both.

[jstac]

My vote is that we do the minimum to make this work nicely, avoiding changes unless a user requests them.

[mmcky]

Great -- let's keep the syntax matching sphinxcontrib-proof then.

I think that is a good direction. While I find {proof:exercise} a bit of an odd syntax we can always add in an {exercise} directive later.

Thanks for comments everyone.