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

automated update to example web docs #138

Open
ryancoe opened this issue May 5, 2020 · 2 comments
Open

automated update to example web docs #138

ryancoe opened this issue May 5, 2020 · 2 comments
Labels
cleanup/useability Improvements to structure, etc. documentation Improvements or additions to documentation examples Tutorials and examples proposal A proposal, for discussion with the development team

Comments

@ryancoe
Copy link
Member

ryancoe commented May 5, 2020

@gbacelli noticed that web documentation for chebfun is built using the MATLAB publish command.

https://www.chebfun.org/docs/guide/guide01.html

While I think we might need to complete #97 for this to be totally automated, at the very least implementing this would save the user the tedious work of correcting the line numbers in example.rst by hand.

I gave this a try with our existing example.m file (obviously you can write the .m to better support this - chebfun also notes that they use a custom style sheet):

>> publish('example.m','html')

ans =

    '/Users/rcoe/Documents/WecOptTool/WecOptTool/html/example.html'

image

@ryancoe ryancoe added documentation Improvements or additions to documentation cleanup/useability Improvements to structure, etc. examples Tutorials and examples labels May 5, 2020
@H0R5E
Copy link
Member

H0R5E commented May 6, 2020

It would certainly be nice to not have to update those line numbers!

There are a couple of downside / challenges to this:

  1. The actual example file is going to have a lot more comments than code
  2. The formatting is going to look a bit different compared to the rest of the sphinx docs
  3. Linking to other parts of the docs will be quite verbose (and unreliable?)
  4. We won't be able to automate this in travis (until we get CI unit testing for MATLAB #97) so we would have to generate and place the generated file manually before merging.

It's probably worth a try to see how it compares to what we have.

@H0R5E H0R5E added the proposal A proposal, for discussion with the development team label May 6, 2020
@ryancoe
Copy link
Member Author

ryancoe commented May 6, 2020

  1. yes, very true
  2. perhaps, but I think that this can be partially addressed by setting the stylesheet (not sure how cumbersome this would be and/or whether we can find something existing on the web)
  3. true, may have to reduce the degree to which this is done?
  4. yes, would still be a checkbox in the PR template

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cleanup/useability Improvements to structure, etc. documentation Improvements or additions to documentation examples Tutorials and examples proposal A proposal, for discussion with the development team
Projects
None yet
Development

No branches or pull requests

2 participants