Skip to content

Merge API docs and reorganize files into folders that match the sidebar navigation #484

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

Merged
merged 28 commits into from
Nov 21, 2024

Conversation

samglover
Copy link
Contributor

@samglover samglover commented Nov 15, 2024

This PR closes #419 by reorganizing the non-auto-generated documentation into the same folder structure (was reference, and now components to match the sidebar navigation) used by pydoc-markdown when it auto-generates the API documentation pages.

This PR also closes #415 by moving pages into folders that match up more closely with the sidebars.

Additionally:

  • Most (if not all) links now point to the file rather than the slug. This should be easier to maintain and update.
  • I removed a couple of localhost URLs
  • And a bunch of assemblyline.suffolklitlab.org URLs, which should have been relative URLs
  • I also updated the NPM packages to address security warnings

@samglover
Copy link
Contributor Author

After some helpful feedback from @plocket I realized that by editing slugs and links I changed more than I wanted to. With these last few commits I have restored the existing page slugs, except where it made more sense to use something else.

Each folder has an "overview" page, plus whatever other pages make sense. I changed some file names, but now that most of the links uses the file location instead of the URL path, it's easy to find and replace file names if we ever want to change them, without changing the actual link URLs.

Anyway, I think it's good to go.

@nonprofittechy
Copy link
Member

Just doing a partial review here by running the package.

Is "Assembly Line Components" meant to be a link? It's not clickable and not a folder:
image

Clicking any page under "FormFyxer" removes the left navigation:

image

image

Suggest renaming these two categories:

image

Maybe: Efiling Integration (EFSP)

and Automated Testing (ALKiln)

Something that has both the title and the purpose, since the brand name may not be familiar to folks but they are likely to visit our documentation page to learn about both automated testing and e-filing, especially the higher level overview of e-filing.

Should these sections be at the top level, or under Assembly Line Components? I can see arguments both ways, but just wanted to point out that they have assembly line specific requirements:

image

@nonprofittechy
Copy link
Member

Is "Interview projects" a useful category here? Maybe just move both items to the top level?

image

It seems that the two items really overlap quite a lot. I'm guessing when you wrote the project management guide, you didn't want to step on my toes by editing the "Working with teams" guide that I put together, but we should figure out how to synthesize.

One key difference between the 2 is that mine is quite long and detailed, and you might want a quick overview first. But I think there is too much overlapping detail right now between these. I'll open a new issue for that, #485

@samglover
Copy link
Contributor Author

Is "Interview projects" a useful category here? Maybe just move both items to the top level?

I think it is, because I plan to add more sub-pages related to interview project management (see #462, #460, #446, #435, etc.). I just haven't had time, yet. Nor have I had time yet to decide what to do with the Working with teams page. For this PR I was just trying to make the file structure match the nav structure.

@samglover
Copy link
Contributor Author

Just doing a partial review here by running the package.

Is "Assembly Line Components" meant to be a link? It's not clickable and not a folder

Yes, it is just a heading. I think it would be useful to have an overview page for the components, but I think that's beyond the scope of #415 and #419.

Clicking any page under "FormFyxer" removes the left navigation:

I can't replicate this. Could it be a caching issue?

Suggest renaming these two categories:

I don't feel strongly about this, and I'll do as you suggest.

Should these sections be at the top level, or under Assembly Line Components? I can see arguments both ways, but just wanted to point out that they have assembly line specific requirements:

Sounds like they should probably go under AssembyLine, then. That cleans things up nicely!

Copy link
Member

@nonprofittechy nonprofittechy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The parts I tested look good to merge, and I'm okay with deployment as is! Looks like a good start at a more logical structure

@nonprofittechy nonprofittechy merged commit 43c17bc into main Nov 21, 2024
2 checks passed
@samglover samglover deleted the 419_415_merge_reorganize_api_docs branch November 21, 2024 14:53
@samglover samglover restored the 419_415_merge_reorganize_api_docs branch November 21, 2024 15:45
@samglover samglover deleted the 419_415_merge_reorganize_api_docs branch November 21, 2024 15:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
2 participants