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

Inconsistent project documentation? #1504

Closed
mithro opened this issue Nov 24, 2020 · 5 comments · Fixed by #1505
Closed

Inconsistent project documentation? #1504

mithro opened this issue Nov 24, 2020 · 5 comments · Fixed by #1505
Assignees

Comments

@mithro
Copy link
Contributor

mithro commented Nov 24, 2020

The prjxray sphinx docs should be identical when viewed;

  • Directly via prjxray
  • When part of the symbiflow documentation

The documentation when viewed at https://symbiflow.readthedocs.io/projects/prjxray/en/latest/# has a fairly short list under items;

Screenshot from 2020-11-24 09-45-46

Yet, when you view the documentation at https://symbiflow.readthedocs.io/en/latest/ you get a much longer output;

Screenshot from 2020-11-24 09-46-24

@mithro
Copy link
Contributor Author

mithro commented Nov 24, 2020

@tcal-x - This is what you discovered?

@rw1nkler
Copy link
Contributor

rw1nkler commented Nov 24, 2020

Probably, this is due to missing links in the documentation when building (prjxray docs) on RTD:
https://github.com/SymbiFlow/symbiflow-docs/blob/master/source/conf.py#L348

I will check that

@tcal-x
Copy link
Contributor

tcal-x commented Nov 24, 2020

@mithro It was more that on Prjxray docs, after "fuzzers", "minitests", "tools", then my new "Guide.." appeared. On Symbiflow docs, my new "Guide..." doesn't appear at the same point. So perhaps I need to find another file in which to add a link to the new guide.

@tcal-x
Copy link
Contributor

tcal-x commented Dec 1, 2020

To be clear, this issue is unrelated to my original issue, which is that the link for "Guide to adding a new device to an existing family" is missing from the Symbiflow version of the docs. The underlying reason for my issue may be chipsalliance/f4pga#395 , which blocks the prjxray submodule update on symbiflow-docs.

Looking at this PR, now prjxray doc pages have the same section repeated at different points in the hierarchy -- is this intended? Specifically, https://symbiflow--1505.org.readthedocs.build/projects/prjxray/en/1505/db_dev_process/readme.html is linked both from under "Getting Started" and also from under "Database Development Process".

However, without this PR (that is, on the current prjxray docs "latest"), this material ("Quickstart Guide", "C++ Development", "Process", ...) doesn't appear anywhere that I can see.

So we are jumping from not having the material at all, to having it appear at two places in the hierarchy. I will need to look at it more, and maybe look at the history, to understand what is going on.

@tcal-x
Copy link
Contributor

tcal-x commented Dec 1, 2020

Note: the section repetition (the same material appearing at two places in the hierarchy) is what is currently on the Symbiflow version, so it is not something new introduced in this PR. This PR just makes the Prjxray match the existing Symbiflow organization, which has the duplication.

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 a pull request may close this issue.

3 participants