Skip to content

Work out how to host docs for individual tools #4

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.

Sign up for GitHub

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

Jump to bottom
Open
adamltyson opened this issue May 17, 2023 · 5 comments · May be fixed by #329
Open

Work out how to host docs for individual tools #4

adamltyson opened this issue May 17, 2023 · 5 comments · May be fixed by #329
Labels
documentation Improvements or additions to documentation enhancement New feature or request

Comments

@adamltyson
Copy link
Member

Ideally we want:
a) Tool-specific docs to be part of the relevant repo so that docs can be updated along with code (and autogenerated API docs)
b) All docs to be accessible via one site (brainglobe.info)

How do we do this? I haven't found any tool to automate this, the best way seems to be some kind of custom build script. The process could be something like:

  • Include docs in all repos
  • Have a central repo (this one) which contains general BrainGlobe info, and a script to:
    • Find all repos with docs
    • Copy files
    • Build one large site with all appropriate links

Any ideas @alessandrofelder? We should think about this as we start to accumulate more documentation for different parts of the project.
@adamltyson adamltyson added documentation Improvements or additions to documentation enhancement New feature or request labels May 17, 2023
@thisisrick25
Copy link

Hi @adamltyson, are there any constraints on what tech stack should be used to build the website and aggregate the docs?

@adamltyson
Copy link
Member Author

This issue is slightly outdated, we have a single website to host all the docs (this is the repo). What's missing is a way to aggregate the API docs (to be built from the docstrings using Sphinx) into the one site.

@thisisrick25
Copy link

Image

@adamltyson did you mean something like this?

@adamltyson
Copy link
Member Author

Yep, that's what we need. The tricky bit is doing it for every BrainGlobe package, and rendering them on a single website.

@thisisrick25
Copy link

thisisrick25 commented May 7, 2025 •
edited
Loading

I think I figured it out. I will raise a PR once I'm done with the remaining BG packages.
The one thing I am struggling with is that autodoc renders the API docstring in .rst files but not in .md. Either way, I'll raise a PR for now.

This was referenced May 7, 2025
Open
Open
@adamltyson adamltyson mentioned this issue May 23, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation Improvements or additions to documentation enhancement New feature or request
Projects
Core development
Status: Backlog
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Built API docs from the docstrings using Sphinx+autodocs thisisrick25/brainglobe.github.io
2 participants
@adamltyson @thisisrick25