docs based on BTD and deployed with CI

[rodrigomelo9]

@LarsAsplund @umarcor

Months ago, Lars added a tutorial. I know that the idea was to have material for this repo, but not sure about the details. I want to contribute. I added the needed to generate docs. Let me know if the following is useful for you and details such as names/paths:

• Move tutorial/exercise_0* to tdd/excercise_0x.
  • tdd assuming there will be ci. I am ok? there will be a tutorial for TDD and another for CI?
  • I will create original and solution inside each tdd/excercise_0x. src and test are inside original and not needed for separate in a repo.
• I will delete instructions.html (will be generated in the sphinx doc) and I will convert instructions.md into tdd_0x.md (one per exercise). I will add docs.yml for CI (where the doc must be deployed @umarcor?).

Sound good?

[umarcor]

It sounds very good indeed. Thanks for having a go at this!

Move tutorial/exercise_0* to tdd/excercise_0x.

I'm not sure about this. I think it would be cleaner to keep the exercises in the tutorial subdir for now.
What we might do is move the current src, test and run.py into tdd. So, the root of the repo would have the following:

• .github/
  • ...
• tdd/
  • src
  • test
  • run.py
• tutorial/
  • ...
• LICENSE
• README.md
• test.py

tdd assuming there will be ci. I am ok? there will be a tutorial for TDD and another for CI?

There won't be any specific tutorial about CI, for now. The current workflow is a showcase of CI procedures (https://github.com/VUnit/tdd-intro/blob/master/.github/workflows/tests.yml) and there is content in http://vunit.github.io/blog/2020_08_12_continuous_integration_with_vunit_action_in_10_lines_of_code.html and http://vunit.github.io/ci/intro.html (referenced in the README here). We might enhance that documentation and/or the workflow, but I don't think there are more sources to be added in that regard.

I will create original and solution inside each tdd/excercise_0x. src and test are inside original and not needed for separate in a repo.

Maybe the other way? Just remove the original subdir.

I will delete instructions.html (will be generated in the sphinx doc) and I will convert instructions.md into tdd_0x.md (one per exercise).

Will you move the markdown sources somewhere else or will you keep each one in the corresponding subdir?

I will add docs.yml for CI (where the doc must be deployed @umarcor?).

I think it's good to push to branch gh-pages in this same repo. That will be served in vunit.github.io/tdd-intro, and we can use intersphinx from cross-referencing (that's what we do with VUnit-cosim, ghdl, ghdl-cosim, edaa-org, osvb, etc.).

Actually, you can use the BTD Action for that:

• https://github.com/edaa-org/edaa-org.github.io/blob/main/.github/workflows/Doc.yml
• https://github.com/VHDL/pyVHDLModel/blob/master/.github/workflows/Pipeline.yml#L289-L309

---

With regard to the engine, some years ago I wrote a shell script for generating a PDF using pandoc. I pushed that branch some minutes ago: https://github.com/VUnit/tdd-intro/tree/umarcor/tutorial-pdf-pandoc. Nevertheless, I think it is desirable to use Sphinx, as you said. It will provide HTML and PDF outputs, along with better integration with other projects/repos.

[umarcor]

• Maybe this PR should target branch 'tutorial', instead of 'master'. Alternatively, we might merge branch tutorial into master as-is, and then rebase this. @LarsAsplund what do you think?
• @rodrigomelo9 I did not find in the conf.py any statement to tell sphinx were to find the markdown sources. Did you implement that?

[rodrigomelo9]

Ok @umarcor I will apply your suggestions.

Regarding the current doc under tutorial, My idea is:

• Remove the instructions.html files.
• Move (to docs), rename (to exercise_0x.rst) and modify the format (from md to rst) the instructions.md files.

Do you prefer to maintain as Markdown? Is ok to move them to docs? (or do you prefer left them as tutorial/exercise_0x/instructions.md?)

[umarcor]

With regard to changing from markdown to restructuredtext, I do think that is desirable indeed.
However, I am unsure about moving them. Currently, users can copy one exercise and it contains "everything" (sources, explanation and solution). Therefore, I would add a toctree to the index of the docs, where the rst files are referenced from each of the subdirs.

[umarcor]

@rodrigomelo9 this PR seems to contain a single commit now. Is that correct?

[rodrigomelo9]

Yes, a single commit. I applied several of your simplest reviews and then, I forced a push.

[rodrigomelo9]

In this PR I will solve to have the docs generated with BTD in CI.