Documentation improvements

[bug-or-feature]

General task to track areas where the docs can be improved. Some starting points:

• the docs need a general overhaul, the code has changed quite a bit since the bulk of the docs was written
• lots of broken links and broken anchors
• tables of contents need to be re-generated
• remove sections marked 'FIX ME TO BE IMPLEMENTED'
• check / fix all the sample snippets for updated code, old instruments etc

Questions:

• should we create a proper docs site, with readthedocs, GitHub pages, MkDocs or similar?

Some other suggestions:

• more diagrams
• how to run a daily process with guide on common errors/issues and how to resolve (Operations Manual)
• windows production setup
• dealing with errors, resolving issues

[vcaldas]

I agree with the points above.

GH pages for me is the least intuitive and more limited approach. I had good experience with readthedocs and mkdocs. MkDocs seams to me an easy one. I'm happy to make a PR or deploy one on my fork as an example.

One goal I had on my fork was to document all the steps from installing to get the system running in production. One thing I learned is that the documentation today is quite hard to follow. It's very complete in some sessions and others there are quite large jumps.

I don understand that trading is risky and Rob mentioned that many times. However, if we aim to have a tool that is easy to use, we will welcome more users and therefore, the changes of identifying issues may increase.

Few items to consider:

• Update the example code to run on IB in paper trade.
• The relationship between the config files, specially when setting up the strategies_list is a bit confusing sometimes.
• Documents on containerized production setup
• Diagram with the data workflow and clarity on the expected behavior. PST is very flexible and that's amazing. But we could be more prescriptive.

These are just few ideias. I'm trying to get my system working e2e before start contributing.

[vcaldas]

On a side note, there's also Sphinx for documentation that is able to generate pages based on docstrings. When I look on how the code is setup today, we won't benefit too much from that automation.

[adnan-trader]

I don't have any experience on web-based documentation, but I am happy to contribute to the content once a solution has been agreed.

One section in particular that needs to be upgraded is that of updating the repo files using IB data AND roll calendars. As this is usually the first thing a new user encounters when thinking of either updating the provided model backtests or moving to production. There are many issues/questions raised here on how to do this while trying to follow the steps.

Agree with @vcaldas and similar to him, I am also in the middle of documenting end-to-end set up for my own sanity! It would be great for the community/users to not have to duplicate the work as they see the deficiencies in the current docs. Also, this will reduce the questions users have and reduce burden on the community power users (@bug-or-feature, @tgibson11). As running the system is where the money hits the road, there has to be better docs on how to do that with pysystemtrade. We all benefit from good docs! :)

[vcaldas]

@bug-or-feature this is an POC of what I suggest:
https://vcaldas.github.io/aptrade/

It's deployed using GH actions and the link would be: robcarver17.github.io/pysystemtrade

For local development, a virtual environment would be better but I found no issue with dependencies when installing the necessary packages.

The search bar works!

If that is a good feature, I'll make into a PR. Let me know.

[bug-or-feature]

@bug-or-feature this is an POC of what I suggest: https://vcaldas.github.io/aptrade/

It's deployed using GH actions and the link would be: robcarver17.github.io/pysystemtrade

For local development, a virtual environment would be better but I found no issue with dependencies when installing the necessary packages.

The search bar works!

If that is a good feature, I'll make into a PR. Let me know.

This approach won't work with pysystemtrade. Rob doesn't have time, and I'm just a collaborator. I don't have access to project settings, or write access to other repos. It might be nice one day to have a pretty published site somewhere, but right now it's more important to fix the content

[vcaldas]

Sounds like a plan then.. I'll keep that being developed in my fork.

[vcaldas]

One note. There is no need for access to other repos. Github has a default branch that uses for publishing pages. The default is 'gh-pages' and all the resto is automated.

What happens is sometimes that pages repo points to "main" or "docs" and then the pipeline can't find. Besides that, there is no other change needed.

[bug-or-feature]

I think it would be useful to have a compiled list of solutions for problems, maybe a FAQ. There's a lot of very useful content distributed around the issues and discussions - it would be good to find links to the best bits in one place. Examples:

• Question: what does 'delayed optimal positions' mean in the Status report?
• Answer: see here

[tgibson11]

• Question: what does 'delayed optimal positions' mean in the Status report?
• Answer: see here

That's just one of many possible causes though.

[vcaldas]

@tgibson11 @bug-or-feature I finally got my system up and running from scratch. I will then focus on the documentations updates for that part. I think if we have a lower entry barrier for the tool we might collect a lot of new users - and hope the whole project does not become a helpdesk =)

[spazio]

@vcaldas If you had time to update the docs from your experience of getting your system up and running from scratch ! I would be available to test it! As I tried to deploy the tool, I'm facing a lot of what I read here and wondering if it worth the time or just find another project that just works out of the box. Completely agree on lowering the barrier.
Let me know!
@bug-or-feature Can you get access to the project to update the docs if we go in this direction?