Use DocFx code sample syntax for samples in documentation *.md files

[IgorFedchenko]

trafficstars

We have documentation articles under docs/articles folder, many of them include code snippets.

Instead of having code pasted directly into articles, need to reference the code samples using DocFx markdown syntax https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#code-snippet.

This guarantees that in the event that we refactor / change APIs, the example included in the documentation will break, so at least all examples are statically type checked.

Here is a list of documents which need to be updated:

Actors

• [ ] docs/articles/actors/fault-tolerance.md
• [ ] docs/articles/actors/mailboxes.md
• [ ] docs/articles/actors/untyped-actor-api.md
• [ ] docs/articles/actors/receive-actor-api.md
• [ ] docs/articles/actors/mailboxes.md
• [ ] docs/articles/actors/di-core.md
• [ ] docs/articles/actors/inbox.md
• [ ] docs/articles/actors/dependency-injection.md
• [ ] docs/articles/actors/routers.md
• [ ] docs/articles/actors/testing-actor-systems.md

Concepts

• [ ] docs/articles/concepts/supervision.md
• [ ] docs/articles/concepts/configuration.md

Intro

• [ ] docs/articles/intro/use-case-and-deployment-scenarios.md

Networking

• [ ] docs/articles/intro/multi-node-test-kit.md
• [ ] docs/articles/intro/serialization.md

Clustering

• [ ] docs/articles/clustering/cluster-client.md
• [ ] docs/articles/clustering/cluster-extension.md
• [ ] docs/articles/clustering/cluster-sharding.md
• [ ] docs/articles/clustering/cluster-singleton.md
• [ ] docs/articles/clustering/distributed-data.md
• [ ] docs/articles/clustering/distributed-publish-subscribe.md
• [ ] docs/articles/clustering/distributed-data.md
• [ ] docs/articles/clustering/split-brain-resolver.md

Persistence

• [ ] docs/articles/persistence/event-sourcing.md
• [ ] docs/articles/persistence/event-adapters.md
• [ ] docs/articles/persistence/persistent-fsm.md
• [ ] docs/articles/persistence/persistent-query.md

Remoting

• [ ] docs/articles/remoting/deathwatch.md
• [ ] docs/articles/remoting/deployment.md
• [ ] docs/articles/remoting/messaging.md

Streams

• [ ] docs/articles/streams/basics.md
• [ ] docs/articles/streams/quickstart.md
• [ ] docs/articles/streams/cookbook.md
• [ ] docs/articles/streams/custom-stream-processing.md
• [ ] docs/articles/streams/integration.md
• [ ] docs/articles/streams/error-handling.md
• [ ] docs/articles/streams/streamrefs.md
• [ ] docs/articles/streams/modularitycomposition.md
• [ ] docs/articles/streams/workingwithgraphs.md
• [ ] docs/articles/streams/workingwithstreamingio.md
• [ ] docs/articles/streams/buffersandworkingwithrate.md
• [ ] docs/articles/streams/pipelineandparallelism.md
• [ ] docs/articles/streams/reactivetweets.md
• [ ] docs/articles/streams/testingstreams.md

Testing

• [ ] docs/articles/testing/multi-node-testing.md

Utilities

• [ ] docs/articles/utilities/serilog.md
• [ ] docs/articles/utilities/event-bus.md
• [ ] docs/articles/utilities/scheduler.md

[Aaronontheweb]

@IgorFedchenko Let's start a checklist here of some specific pages that need to be cleaned up.

[IgorFedchenko]

@Aaronontheweb Good idea, updated issue description. I did not include all the files where c# code is pasted - but included those where some important APIs are introduced (which we need to always be up-to-date for new users), or code blocks are big enough/contain some special methods/parameters that can be easily changed in future releases.

Feel free to update this list (i.e. cut off some points) if you think that we do not need that much changes.

[ghost]

@IgorFedchenko

Not sure if this is relevant for what you're doing but I wrote a small program that will convert the docfx line number type references to region type references. If you're making a large number of doc/md changes then I'd like to run the program to convert the remaining line number references to regions should we create a shared branch for this to catch it all in one build?

https://gist.github.com/nagytech/bb07f1c46cda7b88ed8c3a5f4df7e00b

[Aaronontheweb]

That would be very useful @nagytech

[IgorFedchenko]

@nagytech Nice work! This would be very nice to reference tags instead of fixed line numbers.

But recently @Aaronontheweb you mentioned that would be read to get rid of all that #region tagname / #endregion tagname things and use DocFx // <tagname> / // </tagname> syntax instead. So should we update @nagytech 's program to insert that type of tags instead of regions?

Another thought is that this two changes (changing pasted code to references and changing referenced line numbers to tags references) are independent, so maybe better to make separate issue (and PR) for that? To make update process and review cleaner.

[ghost]

Two separate PRs sounds fine to me.

I’ll create a separate issue and look into the tagname syntax.

On Fri, 31 Jan 2020 at 7:39 pm, Igor Fedchenko [email protected] wrote:

@nagytech https://github.com/nagytech Nice work! This would be very nice to reference tags instead of fixed line numbers.

But recently @Aaronontheweb https://github.com/Aaronontheweb you mentioned that would be read to get rid of all that #region tagname / #endregion tagname things and use DocFx // / // syntax instead. So should we update @nagytech https://github.com/nagytech 's program to insert that type of tags instead of regions?

Another thought is that this two changes (changing pasted code to references and changing referenced line numbers to tags references) are independent, so maybe better to make separate issue (and PR) for that? To make update process and review cleaner.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/akkadotnet/akka.net/issues/4169?email_source=notifications&email_token=ACBFOUON6RYKBZLQXWGLLPLRAPPUVA5CNFSM4KMVXTUKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEKN5SZI#issuecomment-580639077, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACBFOUOAK4QSYJ4PKLY2663RAPPUVANCNFSM4KMVXTUA .