Init Sphinx Docs #1
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This is setup with the initial sphinx docs, generated using `sphinx-quickstart` To build docs, run the following `pip install sphinx` `cd docs` `make html` and that will run the build process for the docs, which should create html pages within `docs/build/html`. This can be set down the line to be run in a github action and pushed to a separate branch for official deployement.
This workflow is a standard github action set to run on any commits/pull requests to `main` Additionally, the required packages for development needed to be included in the `setup.py`. This should eventually be moved to a more modern `pyproject.toml` file which allows for specifically differentiating the pip install between basic, dev, docs, etc. but for now this should be fine.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview
This is an initial sphinx documentation that generates HTML webpages automatically upon any commit/pull request with main. The base of the docs was generated using
sphinx-quickstartto create the general files. Additionally I usedsphinx-apidoc -o ./source ../superneuromatwhich helped generate thesuperneuromat.rstfile. Using this you can run the following commands (which are in thedocs.yamlworkflow) to generate the docs.pip install .cd docsmake htmlThese are very preliminary, but it generates the main files in
docs/build/htmlthat can be connected to github pages for deployment.To see this deployed checkout my fork - https://joey-kilgore.github.io/superneuromat/
Specifics on changes
.gitignore- ignores the extra files from the docs, as well as standard python generated files that should be ignored (including a virtual environment)docs- all of this is the generated files from sphinxsuperneuromat/__init__.py- this file needs to exist for sphinx to find the modulesetup.py- add the additional dependencies needed for building docs/development (pytest and sphinx)Notes for project admin
To deploy this documentation the following steps need to be taken:
deploy from branchand choose branchgh-pagesand the/rootdirectoryOnce this is merged and the action runs, it will take a few minutes but then will automatically deploy.