Developer documentation

[Kevin Rushforth]

Not scripts, but yes, the JDK uses pandoc to process their markdown 
files. I'd prefer not to go down that route at this time. The docs we 
are talking about can be rendered directly by the GitHub UI.

-- Kevin


On 5/12/2023 2:00 PM, Andy Goryachev wrote:
>
> Looks like JDK uses a different flavor of markdown:
>
> > % Testing the JDK
>
> https://github.com/openjdk/jdk/blob/38838b344af00b32251b3141350ba4deb3962d6f/doc/testing.md?plain=1#LL1C18-L1C18
>
> Are there any scripts that process the .md in jdk?
>
> -andy
>
> *From: *openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of Marius 
> Hanl <mariushanl at web.de>
> *Date: *Friday, May 12, 2023 at 13:57
> *To: *John Hendrikx <john.hendrikx at gmail.com>
> *Cc: *openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
> *Subject: *Aw: Developer documentation
>
> I like this idea as well. And I agree, especially the snapping insight 
> are good to document as this topic really isn't trivial.
> I think we should stick to the official JDK, which also follows the 
> idea suggested by John.
> See here: https://github.com/openjdk/jdk/tree/master/doc
> -> There is a doc folder in the root directory.
>
>
> The JDK decided to always have a .md as well as a .html file.
> See: https://github.com/openjdk/jdk/blob/master/doc/building.md
> And: https://github.com/openjdk/jdk/blob/master/doc/building.html
>
>
> +1 for the Markdown format (.md). IntelliJ is also able to render this 
> format.
>
> -- Marius
>
> *Gesendet:* Freitag, 12. Mai 2023 um 21:02 Uhr
> *Von:* "John Hendrikx" <john.hendrikx at gmail.com>
> *An:* openjfx-dev at openjdk.org
> *Betreff:* Developer documentation
>
> In PR https://github.com/openjdk/jfx/pull/910 a lot of "new" insights
> were gained in the snapping logic.  Michael Strauss suggested
> documenting this, and I thought we may as well discuss this on the
> mailing list instead of continuing the discussion in that PR.
>
> In my normal line of work, I usually encourage projects to include
> developer documentation as part of the Git repository. This allows any
> developer to access and modify the documentation easily, and allows you
> to keep documentation in sync with relevant commits (and one can ask
> developers to do so as part of the PR).
>
> The documentation is provided in markdown format and is usually stored
> in a /doc folder. If there are multiple modules, there can be
> specialized doc folders per module with a top level doc folder which
> contains an index.md linking all the docs together, and containing
> documentation that is not module specific.
>
> The documentation is intended for developers only, not for users of
> JavaFX, and hence does not need to be published. Markdown files can
> either be read directly in your IDE of choice or online via GitHub/GitLab.
>
> The build documentation may be a good candidate to place there as well.
>
> So, my suggestion would be:
>
> - Create a top level /doc folder, and create module level /doc folders
> as needed when relevant documentation is written
> - In each /doc folder there is an index.md file that links to all
> documentation in that folder
> - A higher level index.md also contains links to child indexes
> - Consider moving the build and any onboarding documentation there
> - The top level README.md should have a link to /doc/index.md
> - Use only GitHub supported markdown features
>
> --John
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20230512/76e91c98/attachment-0001.htm>