Documentation

[Fahad-Ali-Khan-ca]

Description

Hi, I modified some documentation for the algebra module and fixed the side panel. It is no longer showing the paragraphs of the readme. I also added a tutorial tab where you can link the related pages.

Fixes #81

[mattiaisgro]

You've done a wonderful job! The documentation is well written and detailed. I only have two minor questions: from the diff I cannot find changes in the Doxyfile and doxygen-awesome.css files, if no changes were made I would revert changes to those files, meanwhile, the documentation appears to be offset from the function declarations (like one tab left), it would be better to be aligned, but it's a change I can make myself if necessary (mat.h needs to be realigned anyway, too many tabs). Thank you for the great additions!

[Fahad-Ali-Khan-ca]

Hi the doxygen-awesome.css file has remained unchanged however the doxyfile and the 'DoxygenLayout.xml' is needed to make the 'tutorial' tab. Apologies for the alignment problem I will realign them.
Thanks alot for reviewing!

[mattiaisgro]

Hey @Fahad-Ali-Khan-ca , I have made some commits to fix those minor things, the new version should be ready to merge!

[Fahad-Ali-Khan-ca]

Thank you for taking the time to fix the alignment issues and make the necessary commits. I really appreciate your support in getting this pull request ready for merging. I’ve been tied up with final exams recently, which limited my ability to address the changes myself. Once my exams are over, I plan to contribute more actively and continue improving the documentation and other areas.

Thanks again for your help and understanding!

[mattiaisgro]

Don't worry, take your time to study! Send me a message whenever you want to contribute. You can also contact me on LinkedIn to talk directly about the library and such. Good luck with your exams!

[mattiaisgro]

Hey @Fahad-Ali-Khan-ca , I have looked at the online documentation and it is now empty, is there any additional considerations which I should make to setup the new Doxygen pages? The website is https://chaotic-society.github.io/theoretica

[Fahad-Ali-Khan-ca]

Hi @mattiaisgro I am looking into why it is not working on your website and will give you an update in a day.

[Fahad-Ali-Khan-ca]

Hi @mattiaisgro, just a quick reminder that to create the HTML pages, you need to navigate to the build directory and run doxygen Doxyfile. The DoxygenLayout.xml will be automatically included, as it is defined in the Doxyfile.

I tested this by cloning a separate repo from the current master, and it works for me. Here's what it looks like:

[mattiaisgro]

@Fahad-Ali-Khan-ca The current deployment system (in the doxygen workflow) runs doxygen ./build/doxyfile, is it different than changing directory? If that's the case I will change it and see if it works.

[Fahad-Ali-Khan-ca]

Hi @mattiaisgro, this issue is indeed caused by running doxygen ./build/Doxyfile. I think it happens because the paths I defined in the INPUT field are relative:

INPUT = ../README.md ../src tutorial.md ../BIBLIOGRAPHY.md ../CODE_OF_CONDUCT.md ../CODING_STANDARD.md ../CONTRIBUTING.md

When you run doxygen ./build/Doxyfile from the main directory, Doxygen interprets these paths as being one level above the main directory, which causes the issue.

To resolve this, you could either:

1. Change the workflow to explicitly set the working directory:

      - name: Generate Documentation
        working-directory: ./build
        run: doxygen Doxyfile
   
      - name: Deploy Documentation
        uses: JamesIves/github-pages-deploy-action@v4.6.4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: "gh-pages"
          folder: "./build/html"

2. Update the INPUT paths in the Doxyfile to work from the main directory, like this:

   INPUT = README.md src /build/tutorial.md BIBLIOGRAPHY.md CODE_OF_CONDUCT.md CODING_STANDARD.md CONTRIBUTING.md
   

I tested 2 and it works for me when I use doxygen ./build/Doxyfile

[mattiaisgro]

@Fahad-Ali-Khan-ca the second fix doesn't seem to work :/
I can try with the first one

[mattiaisgro]

I have tried the first fix and it works, but the resulting page has some artifacts I believe. Probably the layout and style changed, as well as the Doxygen configuration.