I have finished the tutorial for sphinx-versioning completely. After running the following command, I obtained a new index.html.
sphinx-versioning build -r feature_branch docs docs/_build/html
open docs/_build/html/index.html
However, I want to have version number such as 0.5.0 and 0.6.0 instead of the branches. How to stack the documentation with version numbers instead of the branches? I can't seem to find it in the official sphinx-versioning documentation.
In Pyramid, we create branches with the version number, e.g., 1.10-branch. Alternatively you can use git to tag a version number, then go into the RTD Admin for your project, and under "Versions" activate it for publication.
In the end I realized that sphinx-versioning does not recognize tag, instead it will only recognize release.
However, another problem with sphinx-versioning is that if you are using the autodoc extension, the documentation generated will be the same as your existing version across all branches and versions. The reason is that the autodoc will only generate the documentation with the package you are having on your computer now, it will not automatically download the old package and generate the older version of documentation for you. But there is a workaround for it.
Complete solution (hacks)
Say you have two releases v1.0 and v2.0 on GitHub.
Then you do a git checkout v1.0, and build the html with sphinx-versioning build <your source location> output1.
Similarly, do git checkout v2.0, and build the html with sphinx-versioning build <your source location> output2.
Then you will have two output folders like this:
output1
├── index.html
├── master
├── v1.0
└── v2.0
output2
├── index.html
├── master
├── v1.0
└── v2.0
I am omitting other unimportant files here.
Now, we just need to delete that v1.0 folder under output2 and move the v1.0 folder from output1 to output2. Then you will have a perfectly working autodoc generated documentation together with a working versioning.
Of course, the drawback for this is that the build time would increase exponentially as you have more versions and you need to manually build so many versions. But still works as a quick fix. Maybe we can write a script to do this for us so that we do not need to build them manually?
TL;DR
sphinx-versioning does not support versioning that well especially when you use autodoc. There are hacks to make it works, but it would be very slow and tedious.
If you want something convenient and don't mind having ads on your documentation, just follow Steve Piercy's suggestions and use the hosting service provided by RTD.
Related
I know two ways of hosting an app.
You either go to settings and set source branch and select folder.
You can follow some steps like npm --save install gh-pages, npm run deploy and so on.
I tried to host my app the 1st way, but it shows README file and it doesn't show index.html in public folder.
The "Configuring a publishing source for your GitHub Pages site" does mention choosing a branch and folder.
But:
gh-pages is always a branch, not a folder.
the folder referenced in the documentation seems only to be /docs: try for testing your index.html in docs/ rather than public/.
That being said, try and test the new (Dec. 2021) feature:
GitHub Pages: using GitHub Actions for builds and deployments for public repositories
Today you will begin to see a new workflow running called pages build and deployment in your public GitHub Pages repositories.
This workflow is automatically triggered when you push to the branch configured for GitHub Pages in your repository.
As the name suggests, it builds and deploys your pages site.
The initial benefit of this change is enabling you to see your build logs and any errors that may occur which has been a long standing issue for Pages users.
However, in the future this will enable us to give you the ability to fully customize your pages build and deployment workflow to use any static site generator you want without having to push the build output to a special branch of the repository.
You may notice this workflow uses some new actions actions/pages-deploy, and actions/jekyll-build-pages.
For now these actions are designed to be used in the generated workflow, however, starting early next year we will introduce some additional changes that will enable you to take advantage of them.
Learn more about GitHub Pages
I need to some help to identify the correct solution that would help me create a seamless documentation for my friends.
We have several repositories in which a doc folder with several .MD files are going to be placed
Repo1
|- Readme.MD
|-docs
|- Installation.MD
|- Usage.MD
Repo2
|- Readme.MD
|-docs
|- Installation.MD
|- Usage.MD
Repo3
|- Readme.MD
|-docs
|- Installation.MD
|- Usage.MD
We would like to use something like vuepress to generate a static site.
If there is any tool/framework which can easily solve this issue. I would be grateful
Thanks a lot for any response,we will definitely put below what we have done
You can accomplish this using MkDocs as your static site generator and the multirepo plugin. Below are the steps to get it all setup. I assume you have Python installed and you created a Python venv.
python -m pip install git+https://github.com/jdoiro3/mkdocs-multirepo-plugin
mkdocs new my-project
cd my-project
Add the below to your newly created mkdocs.yml. This will configure the plugin.
plugins:
- multirepo:
repos:
- section: Repo1
import_url: {Repo1 url}
- section: Repo2
import_url: {Repo2 url}
- section: Repo3
import_url: {Repo3 url}
Now, you can run mkdocs serve or mkdocs build, which will build a static site with all the documentation in one site.
Here is an idea,
Initialize a repository, lets call it TheRepo
Add all depending repos (in our case Repo1, Repo2, Repo3) as git submodules to TheRepo
Now we have everything from Repo1, Repo2 and Repo3 into TheRepo, which I assume might be undesirable for a documentation website.
Create a bash script (using find, grep, rm or similar bash charm) to retain the desired *.md files and remove the undesirable source files. Here is a sample on how-to:
// remove everything else that is not markdown file
find . -type f ! -name '*.md' -delete
Initialize vuepress at TheRepo's root and let vuepress generate cosolidated documentation.
If you do a good job at step 3. you can have a seperate section/classification for each individual dependency Repo in the resulting documentation.
To refresh the contents, simple use git submodule update to update documentation and then chain it with script created in step3 as to automate the refresh process.
git submodule update && ./remove-undesirable-files.sh
I’ve been trying to use Sagemaker to run my custom MXNet training job. In all the examples I’ve seen, the code sample looks like this
estimator = MXNet(‘train.py’, role=role, other_params)
estimator.fit(inputs)
What if my train.py relies on a custom module? Given a directory structure like so
.
├── awesome
│ ├── __init__.py
│ └── lib.py
└── train.py
With my train.py file importing from awesome/lib.py, what’s the best way for me to deploy this job on Sagemaker without going through the hassle of creating a Docker container.
Note: all the code in the custom module is just regular mxnet code, organized across various files and helper methods
You can use the parameters source_dir to point to the code location, and a requirements.txt file to add dependencies. This will avoid to touch docker at all. You can see those parameters in the SDK documentation ("Use third party library"), they are available both for training and deployment. See here an mxnet deployment example with additional dependencies in a requirements.txt
https://github.com/aws-samples/sagemaker-yolov3-detection-server/blob/master/mxnet_detection_serving.ipynb
For the main git repository, devanshdalal.github.io, I am unable to choose the src branch to use for deploying, github.com always picks up the master branch. It becomes difficult now, because I now have to push my build/ forlder to master. Is there a way to automate this?
Currently github doesn't support choosing custom folder for repo named like {GITUSER}.github.io -
From community help post
From https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/, the only three options that GitHub Pages recognizes are:
master branch
docs/ folder on the master branch
gh-pages branch
But for repo like {GITUSER}.github.io, having docs/ folder also doesn't work(I couldn't make it work). I faced this similar issue a while back. I was using jekyll to build the static pages for my site. I know It's really frustrating, but as of now what you want, is not possible.
However, I made a workaround to version-control my jekyll project as well the generated static github.io pages.
I maintain a separate repo for the jekyll version of the project(which in your case I guess would be the react project). So locally I have two separate repo -
{my_username}.github.io - > which will contain the static pages, and remote for this local repo would be the {my_username}.gihub.io repo(the static site repo).
I also have a separate repo for the jekyll project. Which has a different remote repo setup. I configured settings for this project in such way that after build, the static pages will be saved in the local repo of {my_username}.github.io folder. then I can just commit and push separately in the two repos.
This way I can keep track of the static pages as well as the jekyll project that builds the static pages.
You only need to make sure that before you configure a publishing source, the branch or folder you want to use as your publishing source already exists in your repository.
This link GithubPages will solve your problem.
We are developing a project built with yeoman angular generator. Now appears the need of "puppetize" it for deployment.
Obviusly the machine serving client part should be provided with a compiled (minimified, optimized) version of the angular project. But I have no idea if we should store it on our bitbucket repo -for example on the master branch when tagging a new release-
I couldn't find any post about this practice and I could use some help.
There are some facts about angular minified version:
It is uglificated and minificated, so code is unreadable and hard to change.
It demands compilation with tool like gruntjs, which takes some time to build each time.
It works on server, but when you choose to deploy non minificated, revisioned version, you can have other problems during adding new versions to same repo - scripts have same name and are cached in browser and possible other problems.
You decided to deploy compiled version to a client machine.
If you are using version control like git. you can add to repo a folder with compiled version, so your repository have sources and dist in same folder. Possibly you have also backend code, sometimes in backend code you can add compiled version to host on server. It's better to have all code and builds in one repo, so you can do this with one command.
In my case, i wrote scripts in java, to copy builded folder to another folder. We use also Visual Studio for backend, so i wrote script adding new filenames to .cs file, so it can be visible by continous integration tool.
Going to a final, create new branch in git from release master branch. It is useful to have copy of your partial work.
I don't know how often you have releases, but you can solve it by having branches in git.
So your branches can look like this:
master
release1
release2
...
Assuming you are doing development on master and copying new versions to releases.