Ceedling
Ceedling copied to clipboard
ThrowTheSwitch
Suggestion for documentation improvements
State of the Documentation and Infrastructure
The entire Ceedling documentation resides as MarkDown and PDF in the repository under the docs directory.
The PDF format is used because
"we like pdf files because they can be made to look nice while still being portable".
However, the PDF format for documentation is not optimal when it comes to collect input to the project - while I still see the benefits.
Suggestion to Improve the Current Status
Ceedling could use ReadTheDocs (RTD) as host for the documentation. This would mean:
- Ceedling could move all documentation to MarkDown, which hopefully attracts developers to contribute to documentation.
- RTD offers the option to make each state of the documentation available as PDF, so this benefit is still there.
Maybe, if it get's simpler to add or fix the documentation, the documentation as a whole will improve.
The Future
For the future, if this idea is considered good: This could also be done for CMock and Unity and then - there would be the great benefit - that we could link from the Ceedling docs at a specific version to the corresponding CMock and Unity documentation and it all just fits together.
Downsides of this Suggestion
It is another service to be used. However, if this suggestion is considered a good idea, I would volunteer to create a first working example and then also maintain it. We would not really lose something if RTD is shut down, as the MarkDown sources are there and they can still be rendered into PDF by different tools locally, and so PDF documentation would still be available.
You can use Sphinx and go with reStructured text, then you also get plugins for the flow charts like PlantUml, etc. It also maybe has something to extract Ruby incode documentation (for C you have Doxygen) and then embed that into the rendered documentation so that we do not have to duplicate or worry about it. And please add it to CI when you decide to do it - no use in maintaining it.
I am very pro text based sources and against PDFs.
We've already been transitioning the documentation from pdf to markdown, for the reasons you've mentioned. I appreciate the tool ideas though. I'll take a look at those. You both have experience with these tools? Anything we should know in advance? Pros/cons?
Sphinx is Python-based, so I don't know how Ruby would connect and if there is something equivalent Ruby based. There are many extensions for whatever you want - from treemaps for code coverage, to traceability between tests requirements/design and implementation. Highly flexible overall. It can output HTML, pdf, latex and few other formats. Only con I see is that it's Python-based.
Hi @Letme, some comments :)
You can use Sphinx and go with reStructured text, then you also get plugins for the flow charts like PlantUml, etc. It also maybe has something to extract Ruby incode documentation (for C you have Doxygen) and then embed that into the rendered documentation so that we do not have to duplicate or worry about it.
As someone how needs to maintain several large reStructuredText documentations I would - for this project - not use reStructuredText and rather use MarkDown:
- MarkDown syntax is way simpler
- reStructuredText is veeery nitpicky about everything and fails to compile very easily, which is good and annoying at the same time
- (I think) We don't need most of the things reStructuredText offers on top compared to MarkDown
- Things like mermaid (to draw diagram etc.) are also supported in MarkDown.
- There are good linters for MarkDown (consistency yay!)
As long there is no super useful feature that is absolutely needed and only provided by reStructuredText I would use MarkDown wherever possible.
(I am not saying reStructuredText is bad - the contrary, I like it - but I would only choose it when the benefits overweight)
And please add it to CI when you decide to do it - no use in maintaining it.
This is something that is done by some CI. For RTD it works like that: GH pushs to RTD, that there are news, and then RTD builds the commit.
What I meant with maintiing is: The whole "thing" needs to be working, i.e., when RTD gets updated, features that better the documentation needs to be added etc.
Hi @mvandervoord
We've already been transitioning the documentation from pdf to markdown, for the reasons you've mentioned. I appreciate the tool ideas though. I'll take a look at those. You both have experience with these tools? Anything we should know in advance? Pros/cons?
I have only worked with RTD as documentation service, but it worked quite well. I am a heavy user of Sphinx and the tools around it are quite good. There are new things popping up like Docusaurus to render docs, but I have not used them, as Sphinx or the combination Sphinx and RTD work so well.
I took the latest commit 6113249b05b91dd747185be8e3551b8e0ebaa43d from test/ceedling_0_32_rc and made some minor changes to the MarkDown files and this is the result.
To see the results open build/html/index.html.
Please bear in mind, that there basically no cleanup has been made on the MarkDown files, so there might be/is much room to improve the docs from presentation and readability points.
If you think this is any good, I could create a Pull request.
@swaldhoer Personally I think Read the Docs is a good option and have pitched it to others for Ceedling. It's become something of a defacto standard. We need to try it all out and weigh pros/cons. Given the tooling it uses, it certainly seems like we wouldn't be left high and dry if it goes out of business. Giant docs — even Markdown — are becoming unwieldy. And, of course, search, indexing, and other typical needs for documentation are missing.
The first goal with documentation for 1.0.0 is to greatly improve it in accuracy and completeness. After 1.0.0 we'll work on usability. One big limitation is simply time and resources. If we have some success in complementary paid services and products under the Ceedling Pro banner, then we can fund work like migrating documentation to a better home.
As I see you closing a lot of the issues simply by stating that they are completed in 1.0.0, yet it would be much more elegant to close them after 1.0.0 is officially out. I see no need for pre-releases anymore - just bump the version up later on, if there are bugfixes or if there are other new features added. CI should automatically release, like it does now.
And another side note about resources part: There were many pull requests open and while I admit that you probably re-coded those in new 1.0.0 codebase it also means all efforts from the people making the pull requests went to waste, and what is worse, they received no recognition (in form of a commit) to Ceedling repository. This is something that I would expect to be changed in very near future, and that is the idea to get the 1.0.0 out asap, so that you might get community contributions helping you. (end of rant). Thanks for all your effort and contributions.
@Letme Your points are valid. I'm sorry if some of my choices and actions in the repository have rubbed you the wrong way.
A reality here is that the project has been in the hole for quite a few years. We're trying to dig out now.
As best as we can, every contributor has been recognized in the Release Notes. Please see the prominent multi-part Thank You section at the top of the document. In fact, you are named in the list.
Particularly with PRs some have been quite difficult to merge. Either (a) because they were expansive and required far too many (often slow) request exchanges for changes or (b) because so much work in various branches had occurred that the merges were nightmares. So, as best as possible, we incorporated the ideas and some of the code changes, thanked the contributors in the PRs, and called them out in the Thank You's.
As for simply pushing the release out followed by fixes, it's not quite that easy. Or, rather, we're choosing a different path. 1.0.0 is a huge set of changes. With that will come a new wave of support requests, questions, and bug reports. To set everyone up for success as best as we can, that means doing as much testing and documentation and quality of life improvements on version tracking, etc. as possible. Perhaps we're being too cautious, but we're also trying to reset the project in some fashion. That includes doing as much as possible to set the stage for being a better open source project for all involved.
Thank you for all your contributions. And thank you for saying what you did here. It shows that you care. If you didn't care, you'd just shrug your shoulders and move on. Please keep making contributions and voicing your opinions. It's gonna take a lot more effort by everyone to course correct and get this whole thing on a better path. It's been a monumental effort over the last year to get as far as we have.
It's nice to have a thank you section in repository, but automated tools like https://codersrank.io/ put more emphasis on authored commits. Like I wrote, please keep that in mind for the future. I think the longer this 1.0.0 is delayed the more people we lose, while we should maybe take a bit more iterative approach as current version seems stable enough. With automated tests we would make contributions easier. About quality the OpenSource has https://www.bestpractices.dev/en that might be interesting, but we can work on that once master (main) is on 1.0.0
Like I wrote: just food for thought.
I think the absolute opposit will happen: if an importend milestone release, like a 1.0.0 release (years after the last stable release) is bad, people will lose interest in such a project.
@swaldhoer & @Letme -- I'm hearing you and you're right. We've let this go on WAY longer than intended. Being 100% honest, I thought it would release back in February.
There were a lot of interactions between features that either were broken before, or we broke during refactoring. Ceedling's self-tests were completely insufficient (I admit the irony here).
The project had changed significantly from the previous release, making merges time consuming. At that time, I had thought the best solution was to continue a release candidate branch to keep these merges to a minimum. I thought this would speed the process up and get us there sooner. This was a bad call and it had the opposite effect (Very few people were using the RC branch and therefore testing and feedback and helpful submissions all slowed)
I had thought that most people would switch to having PR's target that branch. In retrospect this was a terrible assumption. Most people are using the main branch and therefore are going to play there. Most contributors are going to focus on merging to the main branch because they don't want to get in the way of the "impending release". It was a poor choice and I apologize.
The biggest regret I have about recent decisions ties into exactly your concerns, @Letme ... As the two branches diverged, it became more and more frequent that I would have to cherry-pick changes from one branch to the other, because the two branches were so different. It doesn't give the credit deserved AND it's riskier in that I may not capture all the nuance of the changes.
You both (and others) have my apologies for how this has gone. You both (and others) have my appreciation for sticking through it and continuing to support this project.
We want to do better.
I recognize I've said a bajillion times that we're "almost ready" to release. I'm looking at a very very short list of things I feel need to be in this release to minimize headaches. I'm also looking at a much larger list of issues, PR's, etc which I feel a great amount of guilt for ignoring at this time, but I know it's the right thing to do.
We're pushing this release out, and then I'd like to focus on how to do this better next time.
I'd really appreciate it if you'd both think about this: https://github.com/ThrowTheSwitch/Ceedling/issues/913
Thanks again for your candor and support.