-
Notifications
You must be signed in to change notification settings - Fork 19
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
Create Doc Home Page #34
Comments
Please add the documentation label to this issue |
Hey @JustinCappos, If you think I am going in the right direction, It would be motivating if you can assign this issue to me. |
Thanks for the initiative! There's a discussion about retiring the "docs" repo name, and rename it to "specification", which is more accurate for its current content. And as overall doc homepage, we could use in-toto.io: The reason for this proposal is that changing the purpose or complete content of a repo or website might confuse existing users and break other docs, which refer to these repos or sites. |
@lukpueh No, I think we don't have to change complete content of this repo, rather we have to only add source subdirectory and make it visible on the first menu item in the Learn More menu on Also for the existing users the current read-the-doc contain Python reference implementation, which should go into a sub-section of the new home page with the title "Python Reference Documentation" , which will not confuse existing user. Open to your assistance ,if i am wrong!!! |
Sure, we don't completely change the content, but we further broaden the scope of the repo. This makes sense if you think of the repo as what it's currently called, i.e. a general "docs" repo. But it makes less sense, if you think of it as what it actually is, i.e. the "spec" repo. IMO the specification is important enough to have its own dedicated repo, with an intuitive name, e.g. "specification". So one idea is to just carve out the spec documents, dump them to a new repo, and keep this one the general docs repo. This would leave us without a "docs" repo for general docs. But I think in-toto.io could fill that spot.
Same as above, I think moving things around like this will be more disruptive than beneficial. |
Another reason for using in-toto.io for general docs is to bundle our efforts in one place. in-toto.io could already use more maintainers/contributors. If we have two places for general project-wide infos and docs, this situation will probably not get better. |
but we already have one file |
I think there's a misunderstanding. My proposal above is to rename This means there no longer will be a |
Yeah, I got your point now , we can use in-toto.io for general docs makes it easier for new users and rename this repo as specs repo for developers/contributor so that new users gets helpful information without sorting through technical specifications. |
My preferred way of moving forward (independently of repo renames) is to host project-wide usage documentation on in-toto.io, e.g. under the "Get started" tab. A first step could be to submit a similar issue as here against https://github.com/in-toto/in-toto.io/issues to sketch out structure and initial contents. @DarikshaAnsari, would you be interested? Here are some reasons, why I think this is a good idea:
|
@lukpueh Yes!! I am interested working on this.
I am much clear about the objective and expected outcome although regarding the proposed changes I will better need guidance regarding the exact content to be served as We can have a dedicated discussion regarding the further enhancement or your reviews over the proposed changes in the issue I will raise against https://github.com/in-toto/in-toto.io/issues |
I believe the easiest way to proceed is to create the docs home page as the landing page in-toto.io. This URI currently lands on the reference doc for Python Reference Implementation. That doc is logically part of "project-wide docs", so it should be included in the RTD project, but moved down to a subdir, instead of being the landing page. On the home page, there should be a TOC for the "project-wide docs". The TOC should have a section for Implementation Reference Docs, with a link to the Python Reference Implementation reference docs (at their new location), along with links to the reference docs for other implementations (which might be external). I hope this is clear. |
Did you mean in-toto.readthedocs.io? Because in-toto.io currently does not land on the reference doc for Python in-toto.
There has been an agreement in the in-toto community that the Python "reference" implementation should be considered as one of multiple in-toto implementations. That is why I suggested to keep the project-wide docs (in-toto.io) and Python in-toto docs (http://in-toto.readthedocs.io, we can change the name to python-in-toto.readthedocs.io) separate.
Agreed! (except for the part about new location for Python in-toto)
Not entirely. I'd appreciate a comment to my question in https://github.com/in-toto/docs/issues/85#issuecomment-2107148234, that is, whether there is a specific reason to not use in-toto.io for project-wide docs. |
Thanks for the correction, Lukas -- yes, I did indeed mean that the doc home page should be http://in-toto.readthedocs.io/, with a prominent "Documentation" link on the in-toto home page, http://in-toto.io, and another link at the top of the Get Started menu. The point of using http://in-toto.readthedocs.io/ as the doc landing page (rather than, say, in-toto.io/docs) is to keep RTD as the doc development tool, thus avoiding the overhead of starting with a new tool. The project-wide doc home page can point to a Reference Docs section, with a link to the Python Reference Implementation reference docs. The sources for that doc can remain in Read-the-docs, but would need a new landing page - something like http://in-toto.readthedocs.io/referencedocs/python. |
Okay, thanks for clarifying! Given that we actually don't need to start a new tool, but can use the existing in-toto.io static site generator, plus the other arguments for using in-toto.io and against using in-toto.readthedocs.io for project-wide docs, I suggest we implement Judy's plan (#85) in in-toto.io. @DarikshaAnsari has kindly created an issue there: #24 (comment) |
FYI: just transferred the issue from the in-toto/docs repo and updated the issue description as per the discussion |
Now it looks good. I will proceed further with this issue. |
I think this point is creating confusion about whether we have to add a source subdirectory or a docs subdirectory. Can you please make it clear? |
I suggest to create a directory
Here I meant the web URL, where the usage documentation can be browsed, i.e. https://in-toto.io/docs.
|
@lukpueh sir will also try to solve this issue. |
@Ayush9026, while I appreciate your enthusiasm and know there is a lot of work here, you've posted on many of the issues related to the in-toto documentation. I know you are applying for the LFX Mentorship program, which will primarily be based on this issue set, so I'd suggest letting the application process play out before starting any of this work. Note: I don't make the candidate selections, and of course, we welcome contributions outside the mentorship program, but in this case, I'd recommend patience. |
@lukpueh @JustinCappos - in terms of "User doc sub-issues" listed in #46, I'd propose that we take a step back. If you feel that the docs section will grow, I'd suggest switching the entire website over to Hugo + Docsy. Some of the top-velocity CNCF projects use this duo, including:
And more. @DarikshaAnsari could handle the switch. I can offer guidance. If you agree, I'd propose setting up a separate development branch so that @DarikshaAnsari (and I) can submit small incremental updates, and progressively work towards migrating the entire website, while at the same time have deploy previews for the branch. After that, addressing this issue will be trivial. |
I don't have any strong feelings either way. I support this unless @lukpueh objects. |
@chalin, thanks for the links. I didn't know docsy, but it looks a lot like what Dariksha and I had discussed. :) If you can help set this up, that would be great! |
UPDATE 05/27/2024 (transfer issue from in-toto/docs, update issue description)
The landing page URL for the read-the-docs site currently hosts the auto-generated Python reference doc. To use Read the Docs as the site generator, expand and repurpose this URL as the new overall Doc home page, add user-doc build files in user-doc source directory, and modify the destination for the reference-doc build.See Umbrella Doc Issue
https://github.com/in-toto/docsgithub.com/in-toto/in-toto.io to contain the sources for web-based user documentation.Add build files in the docs repo for the chosen static site generation tool to build the new doc home page.Change the destination for the reference doc build. It should go into a sub-section of the home page with the title "Python Reference Documentation"). The makefile and sources for the generated doc are in https://github.com/in-toto/in-toto/tree/develop/docMake it the first menu item in the Learn More menu on the project home page.The text was updated successfully, but these errors were encountered: