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

Documentation needed #4

Open
rsvp opened this issue Jun 19, 2018 · 2 comments
Open

Documentation needed #4

rsvp opened this issue Jun 19, 2018 · 2 comments
Assignees
Labels
enhancement New feature or request good first issue Good for newcomers help wanted Extra attention is needed
Milestone

Comments

@rsvp
Copy link
Contributor

rsvp commented Jun 19, 2018

So far we have relied largely on demonstrative notebooks
at https://github.com/rsvp/fecon235

The source code here at fecon236 is designed to be more
explicit than casual usage, so if you have experience in
setting up a nice documentation framework, please
kindly volunteer.

The current "docs" need a complete redo, one that starts from fresh eyes.
Nobody peeks at the source code unless there is something which
solves their problem or extends their research interest.

As an analogy, Unix-style man pages are really dry,
but the usage examples are most useful in practice.
That's what fecon235 notebooks were intended to do informally,
but as the research topics got more specialized,
formalization of the structure for clarity became necessary,
hence the refactoring into fecon236.

As an example, forecast() used to be called directly,
but now we prefer fe.hw.forecast(). The user may not know
that fe is shorthand for fecon236 (not fecon235), and
that hw is an alias for the holtwinters.py module which
is physically located implicitly under the tsa directory
for time-series analysis.

This is the sort of thing which needs documentation
which should be a skilled blend of unit-based and
integrative explanations.

Let's us know if you would like to join a MathSci team.
Please discuss further at https://gitter.im/MathSci/fecon236

@rsvp rsvp added enhancement New feature or request help wanted Extra attention is needed good first issue Good for newcomers labels Jun 19, 2018
@rsvp
Copy link
Contributor Author

rsvp commented Jun 26, 2018

pydoc.io offers this automated documentation:
https://www.pydoc.io/pypi/fecon236-10.7.0/

... but obviously we are looking for a more human touch.

@rsvp rsvp added this to the Documentation milestone Jul 14, 2018
@rsvp
Copy link
Contributor Author

rsvp commented Jul 26, 2018

Read the Docs, new automated service


  • Would the RTD Sphinx service be any better? Yes, more fine grain control, plus LaTeX.

cc: @MathSci/fecon-docs

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request good first issue Good for newcomers help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

2 participants