Partly outdated documentation

[cyrille-artho]

There are many aspects that are outdated in the documentation:

• The build instructions will need updating, as they sometimes refer to ant being the build tool. (This is still true for JPF extensions; we can update the documentation once the extensions are on Java 11 with Gradle.)
• Eclipse and IntelliJ is not supported right now (remove the documentation referring to them).
• The nomenclature is inconsistent: JPF extensions are sometimes called "modules", and this is not ideal because Java modules were introduced with Java 11. Conversely, listeners etc. are called "extensions", which is confusing. (We should discuss how to change/name things.)
• Contact e-mail addresses are sometimes given, but no longer used. (Point to Discord?)
• The copyright footer.
• The pages on past GSoC years have markup issues in the title and are partly redundant. (Keep?)
• Many other bigger and smaller things.

[cyrille-artho]

Furthermore, we once had a JPF extension template; does this still exist?
A new template with only one file in every subdirectory of src/ would be helpful:

• src/classes/... (one Java model class that replaces a library class)
• src/examples/ (one example "application" to check)
• src/main/ (a small piece of functionality extending jpf-core)
• src/peers/ (a small native peer)
• src/tests/ (one class with unit tests)

[shubham9345]

Hi @cyrille-artho ,
I am new to this repo and I want to contribute on jpf extension template, can you elaborate the above issue and guide me how to proceed further

[cyrille-artho]

Hi @shubham9345 , @Mahmoud-Khawaja has started a small project with a test extension.
Mahmoud, can you please give Shubham access?
The project is mostly ready, but there is a build problem: The model classes are not included in the JAR file, so certain tests fail.
We would like to have the same overall file structure of model and peer classes as in jpf-core.
This is also an opportunity to avoid placing duplicates of some files into the JAR files. The build in jpf-core duplicates certain files, which increases the size of the JAR file unncessarily and may make troubleshooting harder in some cases.

[huntermarchi]

Hi @cyrille-artho, I would like to contribute to the documentation cleanup.
I’m new to the repo, so please let me know which part of the documentation you want me to update first.
I can start by removing outdated references to Ant, Eclipse, IntelliJ, old email addresses, and fixing inconsistent terminology.
If there is any specific file or directory you want me to begin with, I’m ready to work on it.

[cyrille-artho]

Mahmoud has worked on a setup where markdown files from doc are converted and pushed to a web site. However, this was not completely finished so we have not yet merged it.
@Mahmoud-Khawaja , what is the state of that work? Could @huntermarchi perhaps take over and conclude it?

[PritamP20]

Hi @cyrille-artho, I would like to help with the documentation cleanup as well.
If the issue is still open for contributions, I can start with the simpler items such as:

• removing outdated references to Ant, Eclipse, and IntelliJ
• updating old contact email addresses
• fixing the copyright footer
• cleaning up redundant or broken GSoC pages

Please let me know if this is helpful.

[Mahmoud-Khawaja]

Hello there,
sorry for the late reply. This is the reply regarding the test extension: https://javapathfinder.github.io/jpf-core/
you can clone it and try it on your machine. as Cyrille explained the model classes are not included in the jar files and this is also related to the model class loading issue we have (please check this for more info: javapathfinder/jpf-nas#7
).

i will be adding a readme soon explaining how to run the test extension and view the output. also I noticed that some of you might not be very familiar with jpf, and I’m really happy to help you all get started. I highly recommend beginning by watching this video by Cyrille explaining the architecture and main ideas behind JPF: https://www.youtube.com/watch?v=KnN7HkV1iPM&t

After that, you can dive deeper into the documentation: https://javapathfinder.github.io/jpf-core/
(there are still some minor tweaks to be made there).

[Mahmoud-Khawaja]

Regarding the state of work for the docs:
We are migrating jpf documentation from github wikki to a jekyll based static site for better version control and to be maintanable. The site will be deployed via github pages from the branch. and for the jekyll setup please check docs/_config.yml this is configured with proper baseurl and navigation. and for the layout templates please check default.html. they setup it self is pretty simple and does the job for now. What needs to be done is the problems that Cyrille stated in this issue. You will need jekyll server to test it locally and fix those issues.

[PritamP20]

Hi @Mahmoud-Khawaja, thanks for the clarification earlier!

I checked the repository structure, and I can see that the docs/ folder already contains the full Jekyll setup — including _includes, _layouts, assets/css, and the migrated wiki pages. This looks like the static site that GitHub Pages will build from.

I just want to confirm:
Is this docs/ directory the final intended location for the new static documentation site (the one that will be deployed via GitHub Pages)?
If yes, I can start working directly inside this folder to clean up outdated content, fix terminology inconsistencies, and help address the issues mentioned in #563.

[cyrille-artho]

Yes, docs/ is where we want to keep the documentation that is currently on the wiki.
The wiki will get a new entry page that points to the new site. We will keep the rest for reference but no longer update the wiki.
This way, future documentation updates can be applied as pull requests. This also solves a long-standing problem in that the data inside the wiki is not really accessible outside GitHub's web platform and thus "locked in" the way it is currently handled.

[PritamP20]

Thank you
understood now, will start working on it