Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

I think these feature would be great for FORD. #274

Open
wants to merge 17 commits into
base: master
Choose a base branch
from
Open

I think these feature would be great for FORD. #274

wants to merge 17 commits into from

Conversation

kevinhng86
Copy link
Contributor

@kevinhng86 kevinhng86 commented Mar 5, 2019

I added the ability to use @see and @since, of which they are common for document generators.

I added the ability to use the meta "since" keyword.

I added the ability to use a custom license with URL with the syntax custom|||license_name|||license_url.

I also added the MIT license to the list.

Thank you.

@kevinhng86
Copy link
Contributor Author

Do not accept these changes without testing them. I added these features. I used them personally, but I did not fully debug them and I currently do not use all the features so it is not possible for me to have all the test cases.

Also, not all template file updated to be able to absorb the new changes. The codes that I added do need to debug and templates files needed to be updated to be able to absorb the changes.

Also added copy_assets for future implementation. "copy_assets" can be used where the assets folder of a template is not needed.

Besides that, added breadcrumb_pre for future implementation. "breadcrumb_pre" can be used where the documentation is a subnode in a hierarchy.
support for branding, branding_short, and branding_url.
@@ -81,6 +81,7 @@ def stdout_redirector(stream):
'opl': '<a rel="license" href="http://opencontent.org/openpub/">Open Publication License</a>',
'pdl': '<a rel="license" href="http://www.openoffice.org/licenses/PDL.html">Public Documentation License</a>',
'bsd': '<a rel="license" href="http://www.freebsd.org/copyright/freebsd-doc-license.html">FreeBSD Documentation License</a>',
'mit': '<a rel="license" href="https://opensource.org/licenses/">MIT</a>',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

@d7919
Copy link
Contributor

d7919 commented Apr 29, 2019

This seems to be a very large collection of changes/additions etc. (78k lines added to a project around 20k lines in size) I think most of this is from the template example you've added. It might be clearer to split this up into several PRs such that individual features can be reviewed/tested independently (if you don't have time but would be happy for someone else to do this, that's another option).

I'm not a maintainer so this isn't any sort of "official" request, just a suggestion.

@zbeekman
Copy link
Member

@d7919 would you like to be a maintainer? This is certainly helpful feedback, and we need all the help we can get with FORD, since we're all volunteers, typically on more than one open source project, in addition to our day jobs...

@zbeekman
Copy link
Member

@kevinhng86 Please consider @d7919 request for cleanup and splitting into multiple PRs an official request. As it stands, this PR is to massive for me to handle reviewing; I may cherry pick commits in the interim, but I can't review the entire thing.

That having been said, I'm really liking a lot of the changes I see here, so it would be great if you could help out and submit more logically distinct, self-consistent, atomic PRs...

@d7919
Copy link
Contributor

d7919 commented Apr 29, 2019

@d7919 would you like to be a maintainer? This is certainly helpful feedback, and we need all the help we can get with FORD, since we're all volunteers, typically on more than one open source project, in addition to our day jobs...

@zbeekman I'd be very happy to help out where I can.

@kevinhng86
Copy link
Contributor Author

I would love to join the FORD maintainer team and I do agree that these update should be broken up into smaller PRs. I didn't think of that in the beginning. Currently, I am a bit busy. Nonetheless, within a week or two, I could break up the new features into smaller PRs. Thank you for the comments, I just realized that it is easier to debug with smaller PRs.

I do have one request though. Is it possible for someone to give me one example Fortran source file that utilizes all features of FORD? With that, I would be able to debug the new template. Thank you.

@kevinhng86
Copy link
Contributor Author

kevinhng86 commented Sep 23, 2019

Sorry about the long delay, I finally have some time to work on this. I will split this update into many PR.

On top of these. I think I wanted to add another feature, but I am not sure if I could do it myself. Instead of just able to create HTML pages. I think we should give FORD the ability to export the information into a database like MySQL or JSON. In my opinion, that would give a ton of flexibility to what one can do with the generated docs.

For exporting, I think if everyone wanted it, we should all build a database schema that everyone agrees on.

@cmacmackin
Copy link
Contributor

Sorry about the long delay, I finally have some time to work on this. I will split this update into many PR.

On top of these. I think I wanted to add another feature, but I am not sure if I could do it myself. Instead of just able to create HTML pages. I think we should give FORD the ability to export the information into a database like MySQL or JSON. In my opinion, that would give a ton of flexibility to what one can do with the generated docs.

For exporting, I think if everyone wanted it, we should all build a database schema that everyone agrees on.

I agree, that would be a desirable feature and I've been thinking along similar lines recently. I've been working a little bit on a new parser for FORD and, as part of that, thought it would be useful to define a schema of some sort, allowing the information to be exported. I was actually thinking this would be a standalone library on which FORD would come to depend. That way it could also be used for tasks such as linting and static analysis. I've looked at a few different options for exporting the data (#291 ) but have not settled on anything yet.

@zbeekman
Copy link
Member

@cmacmackin you're aware of lfortran, yes? I don't know how mature their parsers are, but they started (prototyping, at least) in python. Also, F18 is promising but has a way to go.

@kevinhng86
Copy link
Contributor Author

Sorry about the long delay, I finally have some time to work on this. I will split this update into many PR.
On top of these. I think I wanted to add another feature, but I am not sure if I could do it myself. Instead of just able to create HTML pages. I think we should give FORD the ability to export the information into a database like MySQL or JSON. In my opinion, that would give a ton of flexibility to what one can do with the generated docs.
For exporting, I think if everyone wanted it, we should all build a database schema that everyone agrees on.

I agree, that would be a desirable feature and I've been thinking along similar lines recently. I've been working a little bit on a new parser for FORD and, as part of that, thought it would be useful to define a schema of some sort, allowing the information to be exported. I was actually thinking this would be a standalone library on which FORD would come to depend. That way it could also be used for tasks such as linting and static analysis. I've looked at a few different options for exporting the data (#291 ) but have not settled on anything yet.

That is great Chris. I think FORD is already a really good program. Nonetheless, I believe if FORD can export the parsed document and codes to multiple formats(i.e website, JSON, database), then FORD will be a very dynamic and flexible program.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants