Describe algorithm for graph layout

[peso]

This is a start on documentation of the main algorithm (issue git-bahn/gleisbau#3).

I have been pushing around with the code for some time and I seem to discover more nuances all the time. I think the full algorithm documentation will take a significant amount of time, and therefore it would be more sensible to write it gradually.

The goal of this PR is to describe all the main steps of the algorithm in broad terms.

[mlange-42]

I have been pushing around with the code for some time and I seem to discover more nuances all the time. I think the full algorithm documentation will take a significant amount of time, and therefore it would be more sensible to write it gradually.

Thank you for starting this! Indeed, it is not a simple algorithm to make this work, and there are quite a few edge cases. As this is only a first ther, I would prefer to keep issue git-bahn/gleisbau#3 open for now.

[peso]

I have been pushing around with the code for some time and I seem to discover more nuances all the time. I think the full algorithm documentation will take a significant amount of time, and therefore it would be more sensible to write it gradually.

Thank you for starting this! Indeed, it is not a simple algorithm to make this work, and there are quite a few edge cases. As this is only a first ther, I would prefer to keep issue git-bahn/gleisbau#3 open for now.

Ok. What would you consider the criteria for closing issue git-bahn/gleisbau#3?

I would have closed it and then continue to work on documentation in general: API, algorithm, inline comments, module docs, usage examples, etc. I agree that the algorithm is important to document, but mostly for maintainers, not for end users. They would rather have examples and API docs, and then assume the magic inside GitGraph "just works".

[mlange-42]

I have been pushing around with the code for some time and I seem to discover more nuances all the time. I think the full algorithm documentation will take a significant amount of time, and therefore it would be more sensible to write it gradually.

Thank you for starting this! Indeed, it is not a simple algorithm to make this work, and there are quite a few edge cases. As this is only a first ther, I would prefer to keep issue git-bahn/gleisbau#3 open for now.

Ok. What would you consider the criteria for closing issue git-bahn/gleisbau#3?

I would have closed it and then continue to work on documentation in general: API, algorithm, inline comments, module docs, usage examples, etc. I agree that the algorithm is important to document, but mostly for maintainers, not for end users. They would rather have examples and API docs, and then assume the magic inside GitGraph "just works".

It looked to me like you would like to document the algorithm in more detail, and there are some TODOs left in the Markdown file.